智能体 API

GeniSpace 提供两种智能体调用协议，以满足不同集成场景的需求：

OpenAI Chat Completions 兼容 API - 完全兼容 OpenAI 聊天完成标准，便于快速迁移
Agent Execution Protocol - GeniSpace 自定义协议，提供更丰富的参数配置和智能体特性

OpenAI Chat Completions 兼容 API

端点

POST /v1/agents/{agentId}/chat

描述

完全兼容 OpenAI Chat Completions API 规范，允许开发者使用现有的 OpenAI SDK 和代码直接与 GeniSpace 智能体交互。

请求参数

参数	类型	必填	描述
`messages`	array	✓	对话消息数组，格式与 OpenAI API 相同
`model`	string	✗	模型名称（可选，智能体会使用配置的默认模型）
`temperature`	number	✗	控制输出随机性，范围 0-2，默认 0.7
`max_tokens`	integer	✗	最大输出令牌数，默认 2000
`top_p`	number	✗	核心采样参数，范围 0-1，默认 1.0
`frequency_penalty`	number	✗	频率惩罚，范围 -2.0 到 2.0，默认 0
`presence_penalty`	number	✗	存在惩罚，范围 -2.0 到 2.0，默认 0
`stream`	boolean	✗	是否流式返回结果，默认 false

消息格式

{
  "role": "system|user|assistant",
  "content": "消息内容"
}

请求示例

非流式请求

curl -X POST "https://api.genitask.cn/v1/agents/agt_123456/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "system",
        "content": "你是一个专业的数据分析师"
      },
      {
        "role": "user", 
        "content": "请分析这个月的销售数据趋势"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 1500
  }'

流式请求

curl -X POST "https://api.genitask.cn/v1/agents/agt_123456/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "请帮我写一份市场分析报告"
      }
    ],
    "stream": true
  }'

响应格式

非流式响应

{
  "id": "chat_123456789",
  "object": "chat.completion",
  "created": 1710835200,
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "基于您提供的要求，我将为您分析这个月的销售数据趋势..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 256,
    "total_tokens": 298
  }
}

流式响应

data: {"id":"chat_123456789","object":"chat.completion.chunk","created":1710835200,"model":"gpt-4","choices":[{"index":0,"delta":{"role":"assistant","content":"基于"},"finish_reason":null}]}

data: {"id":"chat_123456789","object":"chat.completion.chunk","created":1710835200,"model":"gpt-4","choices":[{"index":0,"delta":{"content":"您提供的"},"finish_reason":null}]}

data: {"id":"chat_123456789","object":"chat.completion.chunk","created":1710835200,"model":"gpt-4","choices":[{"index":0,"delta":{"content":"要求"},"finish_reason":null}]}

data: [DONE]

Agent Execution Protocol

端点

POST /v1/agents/{agentId}/execute

描述

GeniSpace 自定义的智能体执行协议，提供更灵活的参数配置和智能体特有功能，如记忆管理、上下文保持等。

请求参数

参数	类型	必填	描述
`inputs`	object	✓	智能体输入参数，包含查询内容和功能开关
`settings`	object	✗	模型参数设置

inputs 参数

inputs 对象包含智能体所需的输入参数和功能配置：

字段	类型	必填	描述
`query`	string	✓	用户查询内容
`memory`	boolean	✗	是否启用记忆功能，默认 false
`context`	boolean	✗	是否启用知识库上下文检索，默认 false
`internet`	boolean	✗	是否启用互联网搜索，默认 false

{
  "inputs": {
    "query": "用户查询内容",
    "memory": true,
    "context": true,
    "internet": false
  }
}

settings 参数

{
  "settings": {
    "temperature": 0.7,
    "maxTokens": 2000,
    "topP": 1.0,
    "presencePenalty": 0,
    "frequencyPenalty": 0,
    "model": "gpt-4"  // 覆盖智能体默认模型
  }
}

请求示例

基础查询

curl -X POST "https://api.genitask.cn/v1/agents/agt_123456/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "query": "你好",
      "memory": true,
      "context": false,
      "internet": false
    },
    "settings": {
      "temperature": 0.7,
      "maxTokens": 2000
    }
  }'

启用所有功能

curl -X POST "https://api.genitask.cn/v1/agents/agt_123456/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": "1299af56-ca52-4498-a0fd-b3da8ad77daf",
  "execution_time": 6.454147815704346,
  "token_usage": {
    "prompt_tokens": 168,
    "completion_tokens": 85,
    "total_tokens": 253
  }
}

响应字段说明

字段	类型	描述
`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 数量

错误处理

两种 API 都遵循相同的错误处理格式：

{
  "error": {
    "code": "agent_not_found",
    "message": "指定的智能体不存在",
    "details": {
      "agent_id": "agt_123456"
    }
  }
}

常见错误代码

错误代码	描述
`agent_not_found`	智能体不存在
`agent_inactive`	智能体已停用
`invalid_input`	输入参数无效
`quota_exceeded`	配额超出限制
`model_unavailable`	指定模型不可用
`context_too_long`	上下文长度超出限制

最佳实践

选择合适的协议

使用 Chat Completions API 当：
- 需要快速迁移现有 OpenAI 代码
- 构建简单的聊天机器人
- 不需要智能体的高级功能（记忆、知识库、网络搜索）
- 需要完全兼容 OpenAI SDK
使用 Agent Execution Protocol 当：
- 需要利用智能体的记忆功能
- 需要集成知识库进行上下文检索
- 需要网络搜索能力
- 需要更详细的执行统计信息（执行时间、Token 使用等）
- 构建企业级智能应用

性能优化

根据需求选择性启用功能：memory、context、internet
合理设置 maxTokens 以控制响应长度和成本
根据任务复杂度调整 temperature 参数
定期清理不必要的记忆数据以提升检索效率

安全考虑

始终验证用户输入，避免注入攻击
在生产环境中限制智能体的权限范围
定期审查智能体的执行日志
对敏感数据进行适当的脱敏处理

SDK 支持

Python SDK

from genitask import Client

client = Client(api_key="YOUR_API_KEY")

# OpenAI 兼容方式
response = client.agents.chat(
    agent_id="agt_123456",
    messages=[
        {"role": "user", "content": "分析销售数据"}
    ],
    temperature=0.7
)

# Agent Execution Protocol
response = client.agents.execute(
    agent_id="agt_123456", 
    inputs={
        "query": "分析销售数据",
        "memory": True,
        "context": True,
        "internet": False
    },
    settings={
        "temperature": 0.7,
        "maxTokens": 2000
    }
)

JavaScript SDK

import { GeniSpaceClient } from '@genitask/sdk';

const client = new GeniSpaceClient({ apiKey: 'YOUR_API_KEY' });

// OpenAI 兼容方式
const chatResponse = await client.agents.chat('agt_123456', {
  messages: [
    { role: 'user', content: '分析销售数据' }
  ],
  temperature: 0.7
});

// Agent Execution Protocol  
const execResponse = await client.agents.execute('agt_123456', {
  inputs: {
    query: '分析销售数据',
    memory: true,
    context: true,
    internet: false
  },
  settings: {
    temperature: 0.7,
    maxTokens: 2000
  }
});

OpenAI Chat Completions 兼容 API​

端点​

描述​

请求参数​

消息格式​

请求示例​

非流式请求​

流式请求​

响应格式​

非流式响应​

流式响应​

Agent Execution Protocol​

端点​

描述​

请求参数​

inputs 参数​

settings 参数​

请求示例​

基础查询​

启用所有功能​

响应格式​

成功响应​

响应字段说明​

错误处理​

常见错误代码​

最佳实践​

选择合适的协议​

性能优化​

安全考虑​

SDK 支持​

Python SDK​

JavaScript SDK​

相关文档​

OpenAI Chat Completions 兼容 API

端点

描述

请求参数

消息格式

请求示例

非流式请求

流式请求

响应格式

非流式响应

流式响应

Agent Execution Protocol

端点

描述

请求参数

inputs 参数

settings 参数

请求示例

基础查询

启用所有功能

响应格式

成功响应

响应字段说明

错误处理

常见错误代码

最佳实践

选择合适的协议

性能优化

安全考虑

SDK 支持

Python SDK

JavaScript SDK

相关文档