实战手册（Cookbook）

最常见对接场景的可复制示例。每个都是完整、可直接运行的代码——你无需自己对接工具或模型；平台自动路由、自动调用工具、流式返回结果。

1. 一行代码的 Agent（从这里开始）

最简单的对接——发一个任务，读取流式答案。平台自动选模型、自动调用任务所需的任何工具（网页搜索、你的知识库、代码……），并返回结果。本文档里的其他一切，都只是对这个基础用法的可选增强。

bash

curl -N https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "用 3 个要点总结今天最重要的 AI 新闻。"}'
# -> {"run_id":"…","trace_id":"…"}  （然后用 /agent/runs/{run_id}/attach 读取结果）

python

import json, os, requests

WS = os.environ["NEXEVO_WORKSPACE"]
KEY = os.environ["NEXEVO_API_KEY"]

# 1. 启动运行
r = requests.post(
    f"https://nexevo.ai/v1/workspaces/{WS}/agent/runs",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"task": "用 3 个要点总结今天最重要的 AI 新闻。"},
)
run_id = r.json()["run_id"]

# 2. 读取流式结果
stream = requests.get(
    f"https://nexevo.ai/v1/workspaces/{WS}/agent/runs/{run_id}/attach",
    headers={"Authorization": f"Bearer {KEY}"},
    stream=True,
)
for line in stream.iter_lines():
    if not line or not line.startswith(b"data: "):
        continue
    payload = line[6:]
    if payload == b"[DONE]":
        break
    event = json.loads(payload)
    if event.get("type") == "run_end":
        print(event["final_text"])

2. 用 OpenAI SDK（零改造）

已经在用 OpenAI 或 Anthropic SDK？只需改两行——base URL 和 API key——指向 Nexevo 即可。现有代码继续工作，并免费获得智能路由和计费。

python

from openai import OpenAI

client = OpenAI(
    base_url="https://nexevo.ai/v1",
    api_key=os.environ["NEXEVO_API_KEY"],  # 你的 Nexevo 工作区密钥
)

resp = client.chat.completions.create(
    model="nexevo-auto",  # 让 Nexevo 的路由器选模型
    messages=[{"role": "user", "content": "用两句话解释 SEPA Instant。"}],
)
print(resp.choices[0].message.content)

model 填 nexevo-auto 让路由器自动选择，或传一个显式模型 id。Anthropic SDK + 流式的用法见兼容指南。

3. 查询你自己的知识库

把文档上传到一个Project，然后针对它们提问。agent 会自动对你的知识使用 rag_search——无需单独搭建向量数据库或检索管道。

bash

# 针对一个项目的知识库运行 agent
curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "我们的年付计划退款政策是什么？",
    "project_id": "'"$PROJECT_ID"'"
  }'

4. 以专家角色运行

通过传入 persona_slug，赋予 agent 一个领域身份——法律顾问、数据分析师、品牌守护者。角色塑造它的推理方式；工具全部保留可用。

bash

curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "审查我们的隐私政策，找出 GDPR 合规缺口。",
    "persona_slug": "legal-privacy-counsel"
  }'

用 GET /v1/workspaces/{workspace_id}/skill-library 列出可用角色（过滤 kind: "agency"）。详见专家角色。

5. 定时研报

按 UTC cron 定时运行任务——每日新闻摘要、每周竞品报告。每次触发都是一次普通的 agent 运行；搭配 webhook 可在完成时收到通知。

bash

# 每个工作日 UTC 9:00
curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/schedules \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "每日竞品摘要",
    "cron_expr": "0 9 * * 1-5",
    "task_text": "找出昨天竞争对手最重要的 3 个动作，逐个总结。",
    "budget_usd": 0.3
  }'

6. 带记忆的多轮对话

需要来回对话时，用 chat 端点配合会话线程。上下文会自动跨轮次携带。

bash

# 创建会话，然后向其中发消息
curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/conversations \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Q3 规划"}'
# -> {"id": "conv_…", ...}

curl -N https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/conversations/conv_…/messages \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "user", "content": "我们 Q2 的亮点是什么？"}'

想让 agent 在所有对话间记住事实？把它们存入Memory一次，agent 会在每次运行时自动回忆相关上下文。