REMOTE AGENTS

把你的 AI 服务接入 NovaLink

只需要实现一个 OpenAI 兼容的 chat completions 接口。NovaLink 负责认证、计费、UI、分发；你专注于模型、RAG、prompt 工程。

你需要提供

• 一个 HTTPS endpoint URL
• 实现 OpenAI 兼容的 SSE 流式响应
• 可选：API key 鉴权
• 模型 / RAG / prompt / 工具逻辑

NovaLink 负责

• 用户登录 / 业务画像注入
• Marketplace 发现 + 公开页 /a/{slug}
• 付费墙 / 试用次数 / 收入分成
• WebSocket 流式 chat UI

协议

NovaLink 会以 OpenAI Chat Completions 的格式向你的 endpoint 发起请求：

Request

http

POST {your-endpoint}
Content-Type: application/json
Authorization: Bearer {your-api-key}     # optional

{
  "model": "your-model-name",
  "messages": [
    { "role": "system",    "content": "You are a helpful assistant." },
    { "role": "user",      "content": "Hello!" },
    { "role": "assistant", "content": "Hi there!" },
    { "role": "user",      "content": "What's the weather?" }
  ],
  "stream": true
}

你的服务必须返回 text/event-stream 类型的 SSE 流：

Response (SSE)

sse

data: {"choices":[{"delta":{"content":"It"}}]}

data: {"choices":[{"delta":{"content":" looks"}}]}

data: {"choices":[{"delta":{"content":" sunny"}}]}

data: {"choices":[{"delta":{"content":" today."}}]}

data: [DONE]

关键格式要求

每个 chunk 必须以 data: 开头，\n\n 结尾
JSON 必须包含 choices[0].delta.content
结束时发送 data: [DONE]
响应必须在 120 秒内开始流式输出

实现示例

选你最熟悉的语言/框架，复制粘贴就能跑：

PythonFastAPI

server.py

python

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
import json

app = FastAPI()

class Message(BaseModel):
    role: str
    content: str

class ChatRequest(BaseModel):
    model: str
    messages: list[Message]
    stream: bool = True

async def stream_response(text: str):
    """Yield SSE chunks. Replace this with your actual model."""
    for word in text.split():
        chunk = {
            "choices": [{"delta": {"content": word + " "}}]
        }
        yield f"data: {json.dumps(chunk)}\n\n"
    yield "data: [DONE]\n\n"

@app.post("/v1/chat/completions")
async def chat(req: ChatRequest):
    user_msg = req.messages[-1].content if req.messages else ""
    # Replace this with your actual LLM / RAG / agent logic
    reply = f"You said: {user_msg}. Hello from my server!"
    return StreamingResponse(stream_response(reply), media_type="text/event-stream")

NodeExpress

server.js

javascript

import express from "express";

const app = express();
app.use(express.json());

app.post("/v1/chat/completions", async (req, res) => {
  const { messages } = req.body;
  const userMsg = messages[messages.length - 1]?.content ?? "";

  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");
  res.setHeader("Connection", "keep-alive");

  // Replace this with your actual LLM / RAG / agent logic
  const reply = `You said: ${userMsg}. Hello from my Node server!`;
  for (const word of reply.split(" ")) {
    const chunk = { choices: [{ delta: { content: word + " " } }] };
    res.write(`data: ${JSON.stringify(chunk)}\n\n`);
    await new Promise((r) => setTimeout(r, 30));
  }
  res.write("data: [DONE]\n\n");
  res.end();
});

app.listen(8000, () => console.log("listening on :8000"));

Ollama本地大模型

setup

bash

# 1. Install and run Ollama
ollama serve

# 2. Pull a model
ollama pull llama3.1

# 3. Use this URL in NovaLink:
#    http://your-public-ip:11434/v1/chat/completions
#
# Ollama already exposes an OpenAI-compatible API on /v1/chat/completions.
# Make sure your server is reachable from the public internet
# (use a reverse proxy + HTTPS for production).

vLLM高性能推理

setup

bash

# 1. Run vLLM with the OpenAI-compatible server
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8000

# 2. Use this URL in NovaLink:
#    http://your-public-ip:8000/v1/chat/completions
#
# vLLM serves an OpenAI-compatible API out of the box.

鉴权

如果你在创建 Agent 时填写了 API key，NovaLink 会在每次请求中加上：

http

Authorization: Bearer YOUR_API_KEY

API key 在数据库中存储，不会返回到任何客户端 UI（即便是创作者自己）。当前为 Demo 阶段，明文存储；后续会接入加密。

常见问题排查

测试连接报「无法连接远端」

检查 endpoint 是否可从公网访问（不能是 localhost / 127.0.0.1 / 内网 IP）。如果在本地开发，可以用 ngrok / cloudflare tunnel 暴露公网地址。

返回 HTTP 200 但没有内容

通常是 SSE 格式错误。确保每个 chunk 是 `data: {...}\n\n` 格式（注意结尾的两个换行），且结束时发 `data: [DONE]`。

测试连接超时

健康检查的超时是 30 秒，正式聊天的超时是 120 秒。如果你的模型首字延迟较长，请优化或预热。

出现 CORS 错误

NovaLink 是从后端发起请求（server-to-server），不会触发浏览器的 CORS。如果出现 CORS 错误说明请求来源不对，请检查 endpoint URL 是否正确。

如何调试请求/响应

在你的服务器上记录日志（请求 body、响应 chunk）。也可以先用 curl 命令本地复现，确保符合协议后再接入。

上线前清单

Endpoint 是 HTTPS（生产环境）
可从公网访问，不是 localhost / 内网
实现 SSE 流式输出（Content-Type: text/event-stream）
返回标准 OpenAI delta 格式
支持 system/user/assistant 三种 role
首字响应 < 30 秒
处理超长上下文（最近 20 条对话历史）
如果有 API key，已正确校验 Authorization 头
用「测试连接」按钮验证通过

准备好了？

创建你的第一个远端 Agent，5 分钟上线。