2 · 第一次 API 调用

目标：用最少代码向 VOLO AI Agent 发送一条消息，并接收流式响应。

---

2.1 核心端点 · submitIntent

VOLO AI 主对话通道是 单端点 POST SSE（对齐 OpenAI / Anthropic / Vercel AI SDK 行业主流）：

POST /api/agent/chat/volo-ai/{sessionId}/intent
Content-Type: application/json
Accept: text/event-stream
Authorization: Bearer $VOLO_API_KEY

请求体（ChatRequest）：

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "userMessage": "你好，请用一句话介绍 VOLO AI",
  "parentTurnId": null,
  "executionMode": "AUTO"
}

字段	类型	说明
sessionId	UUID	会话 ID，需先创建（见下方）
userMessage	string	用户文本
parentTurnId	UUID | null	接续的父 turn（首条为 null）
executionMode	FAST | MAX | AUTO	执行档位，AUTO 自动路由

---

2.2 cURL 跑通

# 1. 准备 sessionId（任意 UUID，首次自动创建）
export SESSION_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')

# 2. POST SSE 流式对话
curl -N -X POST "https://api.volo.ai/api/agent/chat/volo-ai/$SESSION_ID/intent" \
  -H "Authorization: Bearer $VOLO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "userMessage": "你好，请用一句话介绍 VOLO AI",
    "executionMode": "AUTO"
  }'

-N 关键——禁用缓冲，让 SSE 帧实时打印。

---

2.3 SSE 响应帧

返回流（节选）：

event: PROGRESS
data: {"type":"PROGRESS","traceInfo":{...},"message":"正在思考..."}

event: ASSISTANT_DELTA
data: {"type":"ASSISTANT_DELTA","content":"VOLO"}

event: ASSISTANT_DELTA
data: {"type":"ASSISTANT_DELTA","content":" AI"}

event: ASSISTANT_DELTA
data: {"type":"ASSISTANT_DELTA","content":" 是面向生产的多智能体协作平台。"}

event: COMPLETE
data: {"type":"COMPLETE","traceInfo":{...}}

每行 data: 后是 JSON，按 AgentExecutionEvent 协议序列化。完整 34 种 EventType 见 API · Chat。

---

2.4 TypeScript SDK 等价代码

import { VoloClient } from '@volo-ai/sdk'

const client = new VoloClient({
  apiKey: process.env.VOLO_API_KEY!,
  baseURL: 'https://api.volo.ai',
})

const stream = await client.chat.stream({
  sessionId: crypto.randomUUID(),
  userMessage: '你好，请用一句话介绍 VOLO AI',
  executionMode: 'AUTO',
})

for await (const event of stream) {
  if (event.type === 'ASSISTANT_DELTA') {
    process.stdout.write(event.content)
  }
  if (event.type === 'COMPLETE') {
    console.log('\n[stream complete]')
  }
}

完整 SDK 用法 → SDK · TypeScript

---

2.5 流式工具调用拦截

VOLO AI Agent 在 LLM 调用工具时会发送 TOOL_START / TOOL_END 事件，可用于实时显示工具调用动画：

for await (const event of stream) {
  switch (event.type) {
    case 'ASSISTANT_DELTA':
      // 主消息流
      break
    case 'TOOL_START':
      console.log(`[工具] 调用 ${event.toolName}...`)
      break
    case 'TOOL_END':
      console.log(`[工具] ${event.toolName} 完成`)
      break
    case 'RENDER_UI':
      // AI 主动渲染 UI 组件
      break
  }
}

事件正交性规范见 协议 · 事件协议正交性。

---

2.6 错误处理

状态码	含义	处理建议
401	API Key 无效 / 已撤销	检查 Authorization Header
403	配额耗尽	升级订阅或等待月度重置
429	速率限制（默认 60 次/分钟）	退避重试
500 + event:ERROR	后端异常	data.message 为用户友好错误信息

---

下一步 → 第一个 Skill