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": "Summarize today's top AI news in 3 bullets."}'
# -> {"run_id":"…","trace_id":"…"}  (then tail /agent/runs/{run_id}/attach for the result)

python

import json, os, requests

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

# 1. start the run
r = requests.post(
    f"https://nexevo.ai/v1/workspaces/{WS}/agent/runs",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"task": "Summarize today's top AI news in 3 bullets."},
)
run_id = r.json()["run_id"]

# 2. read the streamed result
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"],  # your Nexevo workspace key
)

resp = client.chat.completions.create(
    model="nexevo-auto",  # let Nexevo's router pick the model
    messages=[{"role": "user", "content": "Explain SEPA Instant in two sentences."}],
)
print(resp.choices[0].message.content)

將 nexevo-auto 作為 model 讓路由器選擇，或傳入明確的 model id。Anthropic SDK 與串流的詳情請見相容性指南。

3. 查詢你自己的知識庫

將文件上傳到專案一次，之後就能對它們提問。Agent 會自動對你的知識執行 rag_search——無需另外建置向量資料庫或擷取管線。

bash

# run an agent against a project's knowledge base
curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "What is our refund policy for annual plans?",
    "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": "Audit our privacy policy for GDPR compliance gaps.",
    "persona_slug": "legal-privacy-counsel"
  }'

用 GET /v1/workspaces/{workspace_id}/skill-library 列出可用角色（過濾 kind: "agency"）。請見專家角色。

5. 排程研究摘要

以週期性 UTC cron 排程執行任務——每日新聞摘要、每週競爭者報告。每次觸發都是一次普通的 agent run；可搭配 webhook 在完成時收到通知。

bash

# every weekday at 9:00 UTC
curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/schedules \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily competitor digest",
    "cron_expr": "0 9 * * 1-5",
    "task_text": "Find yesterday's top 3 moves from our competitors and summarize each.",
    "budget_usd": 0.3
  }'

6. 帶記憶的多輪聊天

若有來回對話需求，請使用聊天端點搭配 conversation 對話串。上下文會自動跨輪次延續。

bash

# create a conversation, then chat into it
curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/conversations \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Q3 planning"}'
# -> {"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": "What were our Q2 highlights?"}'

希望 agent 在所有 conversation 之間記住事實嗎？將它們一次性存到 memory，agent 就會在每次 run 自動回憶相關上下文。