智能体 API

GeniSpace 提供两种调用智能体的方式，并为现有 OpenAI 客户端额外提供一个 OpenAI 兼容中继：

多模态对话（/chat）——GeniSpace 原生协议，使用 contents[] 数组，默认通过 Server-Sent Events（SSE）流式返回。支持文本、图片、音频和文件。
智能体执行（/execute）——结构化协议，使用 inputs 对象和智能体特有的功能开关（记忆、知识库上下文、网络搜索），返回紧凑的结果。
OpenAI 兼容中继（/models/v1/*）——如需复用现有的 OpenAI SDK，请将其指向 API 概述中描述的中继接口。智能体 chat 端点本身不兼容 OpenAI 的 messages 格式。

所有智能体调用端点都受智能体访问控制约束：调用方必须拥有目标智能体的访问权限。

多模态对话

端点

POST /api/agents/{agentId}/chat

描述

GeniSpace 原生对话协议。它接受多模态的 contents[] 数组，并默认以 Server-Sent Events（text/event-stream）流式返回响应。该端点不使用 OpenAI 的 messages 格式。

请求参数

参数	类型	必填	描述
`contents`	array	✓	多模态内容数组（不能为空）。每一项的 `type` 为 `text`、`image_url`、`audio` 或 `file`。
`session_id`	string	✗	用于多轮上下文的会话 ID
`stream`	boolean	✗	是否通过 SSE 流式返回结果。默认 `true`。
`settings`	object	✗	模型参数设置（见下文）

`contents` 项结构

{ "type": "text", "text": "消息文本" }
{ "type": "image_url", "image_url": { "url": "https://...", "detail": "auto" } }
{ "type": "audio", "audio_url": { "url": "https://..." } }
{ "type": "file", "file_info": { /* 文件元数据 */ } }

image_url.url 和 audio_url.url 同时接受 HTTP(S) URL 和 data: base64 URI。

`settings` 参数

字段	类型	范围 / 默认	描述
`temperature`	number	0–2	控制输出随机性
`max_tokens`	integer	≥ 1	最大输出 Token 数
`top_p`	number	0–1	核心采样
`frequency_penalty`	number	—	频率惩罚
`presence_penalty`	number	—	存在惩罚

请求示例

流式请求（默认）

curl -X POST "https://api.genispace.cn/api/agents/550e8400-e29b-41d4-a716-446655440000/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "type": "text", "text": "请帮我写一份市场分析报告" }
    ],
    "settings": { "temperature": 0.7, "max_tokens": 2000 }
  }'

多模态请求（文本 + 图片）

curl -X POST "https://api.genispace.cn/api/agents/550e8400-e29b-41d4-a716-446655440000/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "type": "text", "text": "描述这张图表" },
      { "type": "image_url", "image_url": { "url": "https://example.com/chart.png" } }
    ],
    "session_id": "ses_1234567890123_abcdef",
    "stream": false
  }'

响应格式

当 stream 为 true（默认）时，响应的 Content-Type 为 text/event-stream，会在智能体产生输出时发送 SSE data: 行，例如：

data: {"event": "session.started", "session_id": "ses_1234567890123_abcdef"}

data: {"event": "response.completed", "session_id": "ses_1234567890123_abcdef", "tokens_used": 620, "execution_time": 31017}

当 stream 为 false 时，响应为单个 JSON 体。

智能体执行

端点

POST /api/agents/{agentId}/execute

描述

GeniSpace 的结构化执行协议。它接受 inputs 对象，并返回包含回答、耗时和 Token 使用情况的紧凑结果。当您需要单个结构化响应以及可选的智能体功能（如记忆、知识库上下文、网络搜索）时使用该协议。

请求参数

参数	类型	必填	描述
`inputs`	object	✗	智能体输入参数和功能开关（见下文）
`settings`	object	✗	模型参数设置
`stream`	boolean	✗	是否通过 SSE 流式返回结果。默认 `false`。

`inputs` 参数

inputs 对象接受以下已识别字段，以及智能体提示词模板所需的任意自定义变量：

字段	类型	必填	描述
`query`	string	✗	用户查询内容
`session_id`	string	✗	用于多轮上下文的会话 ID
`memory`	boolean	✗	启用记忆功能，默认 `false`
`context`	boolean	✗	启用知识库上下文检索，默认 `false`
`internet`	boolean	✗	启用互联网搜索，默认 `false`
`images`	string[]	✗	图片 URL 或 `data:` base64 URI
`audios`	string[]	✗	音频 URL 或 `data:` base64 URI

{
  "inputs": {
    "query": "用户查询内容",
    "session_id": "ses_1234567890123_abcdef",
    "memory": true,
    "context": true,
    "internet": false,
    "images": ["https://example.com/image1.jpg"]
  }
}

`settings` 参数

字段	类型	范围	描述
`temperature`	number	0–1	控制输出随机性
`maxTokens`	integer	≥ 1	最大输出 Token 数
`top_p`	number	0–1	核心采样
`presence_penalty`	number	—	存在惩罚
`frequency_penalty`	number	—	频率惩罚

{
  "settings": {
    "temperature": 0.7,
    "maxTokens": 2000,
    "top_p": 1.0,
    "presence_penalty": 0,
    "frequency_penalty": 0
  }
}

请求示例

基础查询

curl -X POST "https://api.genispace.cn/api/agents/550e8400-e29b-41d4-a716-446655440000/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "query": "你好",
      "memory": true
    },
    "settings": {
      "temperature": 0.7,
      "maxTokens": 2000
    }
  }'

启用智能体功能

curl -X POST "https://api.genispace.cn/api/agents/550e8400-e29b-41d4-a716-446655440000/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "query": "帮我分析客户满意度数据",
      "memory": true,
      "context": true,
      "internet": true
    },
    "settings": {
      "temperature": 0.3,
      "maxTokens": 1500
    }
  }'

响应格式

成功响应

{
  "answer": "您好！很高兴为您提供帮助……",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "execution_time": 2.35,
  "token_usage": {
    "prompt_tokens": 168,
    "completion_tokens": 85,
    "total_tokens": 253,
    "cost": 0.012
  }
}

响应字段说明

字段	类型	描述
`answer`	string	智能体生成的回答内容
`agent_id`	string	执行的智能体 ID
`execution_time`	number	执行耗时（秒）
`token_usage`	object	Token 使用统计
`token_usage.prompt_tokens`	integer	输入 Token 数量
`token_usage.completion_tokens`	integer	输出 Token 数量
`token_usage.total_tokens`	integer	总 Token 数量
`token_usage.cost`	number	本次执行的计费成本

当 stream 为 true 时，响应将以 SSE（text/event-stream）形式返回，而非单个 JSON 体。

智能体访问控制

创建智能体（POST /api/agents）时，以下字段为必填：name、model 和 systemPrompt。您还可以控制空间内哪些成员可以调用该智能体：

字段	类型	描述
`accessScope`	string	`SPACE`（所有空间成员）或 `RESTRICTED`（仅列出的用户）
`allowedUserIds`	string[]	允许访问 `RESTRICTED` 智能体的用户 ID

列出智能体（GET /api/agents）时，传入 accessibleOnly=true 可仅返回调用方可访问的智能体。所有调用端点都会强制执行该访问控制。

错误处理

所有智能体端点都使用统一的扁平错误信封：

{
  "success": false,
  "message": "Resource not found",
  "code": "NOT_FOUND"
}

常见错误码

错误码	HTTP 状态	描述
`VALIDATION_ERROR`	400	请求参数无效
`UNAUTHORIZED`	401	缺少或无效的凭证
`FORBIDDEN`	403	无目标智能体的访问权限
`NOT_FOUND`	404	智能体不存在
`INSUFFICIENT_TOKENS`	402	Token 余额已耗尽
`SERVER_ERROR`	500	服务器内部错误

完整列表请参见错误处理。

最佳实践

选择合适的协议

使用对话（/chat） 当：
- 需要流式响应（SSE）
- 需要多模态输入（图片、音频、文件）
- 构建交互式对话体验
使用执行（/execute） 当：
- 需要包含 Token 使用情况和耗时的单个结构化结果
- 需要切换智能体功能（记忆、知识库上下文、网络搜索）
- 需要传入自定义提示词模板变量
使用 OpenAI 中继（/models/v1/*） 当：
- 需要复用现有的 OpenAI SDK 或代码库

性能优化

根据需求选择性启用功能：memory、context、internet
合理设置 maxTokens / max_tokens 以控制响应长度和成本
根据任务复杂度调整 temperature 参数

安全考虑

始终验证用户输入，避免注入攻击
在生产环境中通过 accessScope / allowedUserIds 限制智能体访问
对敏感数据进行适当的脱敏处理

SDK 支持

JavaScript SDK

GeniSpace 官方 JavaScript SDK 支持智能体对话与执行，详见开发资源。

import GeniSpace from 'genispace';

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

// 多模态对话（GeniSpace 原生 contents[]）
const chatResponse = await client.agents.chat('550e8400-e29b-41d4-a716-446655440000', {
  contents: [{ type: 'text', text: '分析销售数据' }],
  settings: { temperature: 0.7 }
});

// 智能体执行（结构化 inputs）
const execResponse = await client.agents.execute('550e8400-e29b-41d4-a716-446655440000', {
  inputs: {
    query: '分析销售数据',
    memory: true,
    context: true,
    internet: false
  },
  settings: {
    temperature: 0.7,
    maxTokens: 2000
  }
});

多模态对话​

端点​

描述​

请求参数​

contents 项结构​

settings 参数​

请求示例​

流式请求（默认）​

多模态请求（文本 + 图片）​

响应格式​

智能体执行​

端点​

描述​

请求参数​

inputs 参数​

settings 参数​

请求示例​

基础查询​

启用智能体功能​

响应格式​

成功响应​

响应字段说明​

智能体访问控制​

错误处理​

常见错误码​

最佳实践​

选择合适的协议​

性能优化​

安全考虑​

SDK 支持​

JavaScript SDK​

相关文档​

多模态对话

端点

描述

请求参数

`contents` 项结构

`settings` 参数

请求示例

流式请求（默认）

多模态请求（文本 + 图片）

响应格式

智能体执行

端点

描述

请求参数

`inputs` 参数

`settings` 参数

请求示例

基础查询

启用智能体功能

响应格式

成功响应

响应字段说明

智能体访问控制

错误处理

常见错误码

最佳实践

选择合适的协议

性能优化

安全考虑

SDK 支持

JavaScript SDK

相关文档