Cookbook

Copy-paste recipes for the most common integrations. Each is a complete, runnable example — no wiring up tools or models yourself; the platform auto-routes, auto-calls tools, and streams the result.

1. The one-line agent (start here)

The simplest possible integration — send a task, read the streamed answer. The platform picks the model, calls whatever tools the task needs (web search, your knowledge base, code…), and returns the result. Everything else in these docs is an optional refinement of this.

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. Use the OpenAI SDK (zero rewrite)

Already on the OpenAI or Anthropic SDK? Point it at Nexevo by changing two lines — the base URL and the API key. Your existing code keeps working, with smart routing and billing for free.

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)

Use nexevo-auto as the model to let the router choose, or pass an explicit model id. See the compatibility guide for Anthropic SDK + streaming.

3. Query your own knowledge base

Upload documents to a project once, then ask questions against them. The agent auto-uses rag_search over your knowledge — no separate vector DB or retrieval pipeline to build.

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. Run with a specialist role

Give the agent a domain identity — a legal reviewer, a data analyst, a brand guardian — by passing persona_slug. The role shapes how it reasons; tools stay fully available.

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"
  }'

List available roles with GET /v1/workspaces/{workspace_id}/skill-library (filter kind: "agency"). See Specialist roles.

5. Scheduled research digest

Run a task on a recurring UTC cron schedule — a daily news digest, a weekly competitor report. Each firing is an ordinary agent run; pair with a webhook to get notified when it finishes.

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. Multi-turn chat with memory

For back-and-forth conversation, use the chat endpoint with a conversation thread. Context carries across turns automatically.

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?"}'

Want the agent to remember facts across all conversations? Save them to memory once, and the agent auto-recalls relevant context on every run.