智能体 API

智能体 API 用于调用交互式对话智能体和结构化任务智能体。所有请求都必须具备目标智能体访问权限，并归属于当前认证用户和空间。

选择正确端点

需求	端点	客户端方法
交互式、多模态、流式对话	`POST /api/agents/{agentId}/chat`	`client.agents.chatStream()`
非流式对话结果	`POST /api/agents/{agentId}/chat`，`stream: false`	`client.agents.chat()`
结构化任务智能体执行	`POST /api/agents/{agentId}/execute`	`client.agents.execute()`
长时间任务智能体执行	`POST /api/agent-jobs`	`client.agents.invokeAsync()`
恢复用户选择交互	`POST /api/agents/{agentId}/turns/{turnId}/resume`	HTTP V3 流请求
查看或压缩对话上下文	会话 context 端点	HTTP 请求

不要向智能体 chat 端点发送 OpenAI messages[]。该端点使用 GeniSpace contents[]；Models 中继是另一套 OpenAI 兼容 API。

交互式对话

请求

POST /api/agents/{agentId}/chat
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: text/event-stream
X-GeniSpace-Stream-Protocol: langgraph-v3

{
  "contents": [
    { "type": "text", "text": "请对照制度分析这张图表" },
    { "type": "image_url", "image_url": { "url": "https://example.com/chart.png" } }
  ],
  "session_id": "session-123",
  "turnId": "1a11bb22-333c-444d-855e-666666666666",
  "stream": true,
  "settings": {
    "temperature": 0.3,
    "max_tokens": 2000,
    "chat_mode": "agent",
    "disable_web_search": false
  }
}

contents 不能为空。API 支持 text、image_url、audio 和 file。使用 session_id 延续对话；每个用户轮次生成一个稳定的 UUID turnId，便于安全识别重试。

settings.chat_mode 可为 ask 或 agent。Ask 模式不执行操作型工具。只发送该端点支持的设置，未知字段会被拒绝。

LangGraph V3 流协议

流式请求必须发送 X-GeniSpace-Stream-Protocol: langgraph-v3，响应也必须确认相同值。缺失或不一致会返回 HTTP 426 Upgrade Required。

每个 SSE data: 帧都是带连续序号的 JSON 信封：

{
  "type": "event",
  "method": "custom:genispace",
  "params": { "data": { "event": "content-delta", "delta": "你好" } },
  "seq": 7
}

线上方法包括以 custom:genispace 表达的产品事件，以及 messages、tools、lifecycle 和 input。客户端必须保持顺序，并拒绝序号不连续或不支持的帧。请使用 JavaScript SDK，不要维护第二套解析器。

SDK 会把线上事件投影成产品事件，例如：

session.started；
content.delta；
携带结构化参数和结果元数据的 tool.execution；
knowledge.evidence；
agent.input.required；
local.tool.call；
context.usage；
response.completed；
turn.persist_pending、error.occurred 和 stream.ended。

不要只显示事件描述；工具参数、执行结果、错误、插件元数据和知识证据都属于用户可见的执行过程。

JavaScript SDK 示例

import { GeniSpace } from 'genispace';

const client = new GeniSpace({
  apiKey: process.env.GENISPACE_API_KEY!,
  baseURL: 'https://api.genispace.cn/api',
});

const controller = new AbortController();
const stream = client.agents.chatStream(
  'AGENT_ID',
  {
    contents: [{ type: 'text', text: '查找相关制度证据。' }],
    session_id: 'session-123',
    turnId: crypto.randomUUID(),
    settings: { temperature: 0.2, max_tokens: 1200 },
  },
  { signal: controller.signal, language: 'zh-CN' },
);

for await (const event of stream) {
  if (event.type === 'content.delta') process.stdout.write(event.content ?? '');
  if (event.type === 'tool.execution') renderToolResult(event.metadata);
  if (event.type === 'agent.input.required') renderUserChoice(event.metadata);
  if (event.type === 'error.occurred') throw new Error(event.error);
}

SDK 还导出 AgentStreamClient 和 AgentStreamDecoder，供内置智能体流及字节转发桌面代理使用。

恢复用户选择交互

收到 agent.input.required 后，持久化交互元数据，并渲染服务端给出的单选或多选表单。提交选项 ID，不要提交显示文案：

POST /api/agents/{agentId}/turns/{turnId}/resume
X-GeniSpace-Stream-Protocol: langgraph-v3

{
  "sessionId": "session-123",
  "interactionId": "interaction-456",
  "selectedOptionIds": ["candidate-42"],
  "otherText": null
}

恢复请求会返回另一条 V3 流。重复提交会返回幂等成功，不会执行两次。可通过以下端点列出待处理交互：

GET /api/agents/{agentId}/sessions/{sessionId}/interactions/pending

otherText 只对应表单的自定义答案输入框，客户端不要再自行添加第二个“其他”选项。

上下文状态与压缩

POST /api/agents/{agentId}/sessions/{sessionId}/context/status
POST /api/agents/{agentId}/sessions/{sessionId}/context/compact

公开 API 均接受空 JSON 请求体。状态包含已用、剩余和最大 Token，是否为估算值、压缩次数、摘要状态和消息数。存在待处理用户交互时，手动压缩返回 409；没有 checkpoint 时返回 404。

压缩会汇总模型上下文，不删除持久化聊天记录。详见上下文管理。

结构化任务执行

具有明确输入输出、无需交互界面的任务智能体使用 /execute：

const result = await client.agents.execute('TASK_AGENT_ID', {
  inputs: {
    query: '抽取发票字段',
    documentUrl: 'https://example.com/invoice.pdf',
  },
  settings: { temperature: 0.1, maxTokens: 1200 },
});

可能运行数分钟的操作使用 invokeAsync()。它创建 AGENT_INVOKE Job 并轮询状态，不会长时间占用一个 HTTP 请求：

const result = await client.agents.invokeAsync(
  'invoice-extractor',
  { query: '抽取并校验字段' },
  {
    timeoutMs: 600_000,
    idempotencyKey: 'invoice-2026-00042',
    onProgress: (job) => updateProgress(job.phase, job.progress),
  },
);

停止本地轮询不会取消服务端 Job；需要使用 Job 取消 API 进行协作式取消。

取消轮次

取消正在运行的对话轮次：

POST /api/agents/{agentId}/turns/{turnId}/cancel

{ "sessionId": "session-123" }

同时中止浏览器流，避免界面继续读取。分布式取消到达当前运行实例可能需要短暂时间。

错误

状态	常见原因
400	内容、设置、会话或交互参数错误
401	凭据缺失或无效
402	用户或空间额度不足
403	无智能体、工具或空间资源权限
404	智能体、会话 checkpoint、轮次或交互不存在
409	轮次已运行，或待确认输入阻止上下文压缩
426	缺少或错误的 `langgraph-v3` 流请求头
503	运行时或上下文压缩暂不可用

即使 HTTP 连接最初成功，error.occurred 也表示流失败。诊断时保留 turn ID、request ID 和最后一个有效序号。

安全与可靠性

API Key 应保存在可信服务端；浏览器应用使用已认证 Access Token。
每个用户轮次生成唯一 turnId，只有重试同一轮时才复用。
本地工具只有在宿主应用已经注册和授权时才能执行。
工具证据属于不可信数据，不要作为可执行 HTML 渲染。
遵守空间权限，不请求用户无权查看的输出字段。
有重要后果的后台工作使用幂等键。

选择正确端点​

交互式对话​

请求​

LangGraph V3 流协议​

JavaScript SDK 示例​

恢复用户选择交互​

上下文状态与压缩​

结构化任务执行​

取消轮次​

错误​

安全与可靠性​

相关指南​