Skip to content

API_USAGE.md

Latest commit

 

History

History
242 lines (191 loc) · 4.35 KB

API_USAGE.md

File metadata and controls

242 lines (191 loc) · 4.35 KB

TopicLab-Agent API Usage Documentation

服务启动

cd /workspace/projects
python src/main.py

默认服务地址：http://localhost:8000

API 端点

1. 同步调用（推荐）

端点: POST /run

请求体:

{
  "messages": [
    {
      "type": "human",
      "content": "你的问题"
    }
  ]
}

响应:

{
  "messages": [
    {
      "type": "human",
      "content": "你的问题"
    },
    {
      "type": "ai",
      "content": "Agent 的回答"
    }
  ],
  "run_id": "xxx-xxx-xxx"
}

2. 流式调用

端点: POST /stream

请求体: 同上

响应: Server-Sent Events (SSE) 格式的流式输出

3. OpenAI 兼容接口

端点: POST /v1/chat/completions

请求体:

{
  "model": "topiclab-agent",
  "messages": [
    {
      "role": "user",
      "content": "你的问题"
    }
  ],
  "stream": false
}

调用示例

Python 示例

import requests
import json

# API 地址
API_URL = "http://localhost:8000"

def ask_question(question: str) -> str:
    """调用 Agent 获取回答"""
    
    # 构造请求
    payload = {
        "messages": [
            {
                "type": "human",
                "content": question
            }
        ]
    }
    
    # 发送请求
    response = requests.post(
        f"{API_URL}/run",
        json=payload,
        headers={"Content-Type": "application/json"}
    )
    
    # 解析响应
    result = response.json()
    
    # 提取 AI 回答
    if "messages" in result:
        for msg in reversed(result["messages"]):
            if msg.get("type") == "ai":
                return msg["content"]
    
    return "未获取到回答"

# 使用示例
if __name__ == "__main__":
    question = "如何初始化 topiclab-cli？"
    answer = ask_question(question)
    print(f"问题: {question}")
    print(f"回答:\n{answer}")

cURL 示例

# 同步调用
curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "human",
        "content": "如何初始化 topiclab-cli？"
      }
    ]
  }'

# OpenAI 兼容接口
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "topiclab-agent",
    "messages": [
      {
        "role": "user",
        "content": "查看通知"
      }
    ],
    "stream": false
  }'

JavaScript/TypeScript 示例

const API_URL = 'http://localhost:8000';

async function askQuestion(question) {
  const response = await fetch(`${API_URL}/run`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      messages: [
        {
          type: 'human',
          content: question
        }
      ]
    })
  });
  
  const result = await response.json();
  
  // 提取 AI 回答
  if (result.messages) {
    for (let i = result.messages.length - 1; i >= 0; i--) {
      if (result.messages[i].type === 'ai') {
        return result.messages[i].content;
      }
    }
  }
  
  return '未获取到回答';
}

// 使用示例
(async () => {
  const question = '如何初始化 topiclab-cli？';
  const answer = await askQuestion(question);
  console.log('问题:', question);
  console.log('回答:\n', answer);
})();

环境变量

服务启动前需要设置以下环境变量（已自动配置）：

  • COZE_WORKLOAD_IDENTITY_API_KEY: API 密钥
  • COZE_INTEGRATION_MODEL_BASE_URL: 模型服务地址
  • COZE_WORKSPACE_PATH: 工作目录路径

错误处理

常见错误码

  • 400: 请求格式错误
  • 500: 服务内部错误
  • 504: 请求超时（默认 15 分钟）

错误响应示例

{
  "detail": "Invalid JSON format"
}

性能说明

  • 首次调用: 可能需要 3-5 秒（初始化模型和工具）
  • 后续调用: 1-3 秒（取决于问题复杂度）
  • 文档更新: 每 3 小时自动更新一次 Skill 文档

注意事项

  1. 单轮回复: Agent 会一次性给出完整答案，不会追问
  2. 指令优先: 回答以 topiclab-cli 命令为主
  3. 直接高效: 无冗余解释，适合程序调用
  4. 自动更新: Skill 文档每 3 小时自动更新

健康检查

# 检查服务是否运行
curl http://localhost:8000/health

# 查看服务状态
curl http://localhost:8000/