实用示例

真实世界的 API 来源配置与使用模式

本指南为 xiantong 提供了配置热门服务 API 来源与常见使用模式的实用示例。

配置示例#

GitHub API#

{
"type": "api",
"name": "GitHub",
"tagline": "Access GitHub repositories, issues, and pull requests",
"icon": "https://github.githubassets.com/favicons/favicon.svg",
"api": {
"baseUrl": "https://api.github.com",
"testEndpoint": "/user",
"authType": "bearer"
}
}

Agent 可以执行的示例请求：

# List repositories
GET /user/repos

# Create an issue
POST /repos/{owner}/{repo}/issues
{"title": "Bug report", "body": "Description"}

# Get pull request
GET /repos/{owner}/{repo}/pulls/{pull_number}

OpenAI API#

{
"type": "api",
"name": "OpenAI",
"tagline": "Generate text and embeddings with GPT models",
"icon": "https://openai.com/favicon.ico",
"api": {
"baseUrl": "https://api.openai.com/v1",
"testEndpoint": "/models",
"authType": "bearer"
}
}

Stripe API#

{
"type": "api",
"name": "Stripe",
"tagline": "Manage payments, customers, and subscriptions",
"icon": "https://stripe.com/favicon.ico",
"api": {
"baseUrl": "https://api.stripe.com/v1",
"testEndpoint": "/customers?limit=1",
"authType": "bearer"
}
}

SendGrid API#

{
"type": "api",
"name": "SendGrid",
"tagline": "Send transactional and marketing emails",
"icon": "https://sendgrid.com/favicon.ico",
"api": {
"baseUrl": "https://api.sendgrid.com/v3",
"testEndpoint": "/user/profile",
"authType": "bearer"
}
}

Twilio API#

{
"type": "api",
"name": "Twilio",
"tagline": "Send SMS and make voice calls",
"icon": "https://www.twilio.com/favicon.ico",
"api": {
"baseUrl": "https://api.twilio.com/2010-04-01",
"testEndpoint": "/Accounts/{AccountSid}.json",
"authType": "basic"
}
}

Twilio 使用基本认证，账户 SID 作为用户名，验证令牌作为密码。

认证模式#

令牌（Bearer Token，最常见）#

适用于多数现代 API：

{
"api": {
"baseUrl": "https://api.example.com",
"authType": "bearer"
}
}

使用令牌的服务包括：

• GitHub
• OpenAI
• Stripe
• SendGrid
• Slack

自定义请求头#

部分 API 使用自定义头名称：

{
"api": {
"baseUrl": "https://api.exa.ai",
"authType": "header",
"headerName": "x-api-key"
}
}

使用自定义头的服务：

• Exa（x-api-key）
• Anthropic（x-api-key）
• AWS 服务（多种）

查询参数#

老旧 API 常通过查询参数认证：

{
"api": {
"baseUrl": "https://api.weatherapi.com/v1",
"authType": "query",
"queryParam": "key"
}
}

这会将 ?key={your_api_key} 附加到请求中。

基本认证#

适用于需要用户名/密码的 API：

{
"api": {
"baseUrl": "https://api.twilio.com",
"authType": "basic"
}
}

系统将提示输入用户名与密码。

常见模式#

带版本号的基础 URL#

在基础 URL 中包含版本号：

{
"api": {
"baseUrl": "https://api.example.com/v1"
}
}

租户专属 URL#

针对多租户 API：

{
"api": {
"baseUrl": "https://your-tenant.api.example.com"
}
}

自托管 API#

用于内部或自托管服务：

{
"api": {
"baseUrl": "https://internal-api.yourcompany.com",
"testEndpoint": "/health"
}
}

如何选择测试端点#

请选择满足以下条件的端点：

• 需要认证（验证凭据是否有效）
• 响应快速（轻量级）
• 始终可用（不易受限）

避免使用会修改数据的端点作为测试端点。尽量使用只读取信息的 GET 请求。

使用 API 来源#

配置完成后，xiantong Agent 可以向基础 URL 下的任意端点发送请求。

请求格式#

Agent 通过 HTTP 工具发出请求：

Make a GET request to /users/123

POST to /messages with body: {"text": "Hello", "channel": "general"}

请求头与请求体#

Agent 可以指定：

• HTTP 方法（GET、POST、PUT、DELETE、PATCH）
• 路径（相对于基础 URL）
• 查询参数
• 请求体（JSON）
• 额外的请求头

认证头会被自动添加。

响应处理#

API 响应会被智能处理：

• JSON 响应 会被解析并清晰呈现
• 大型响应 可能会被总结
• 错误 会附带状态码与提示
• 速率限制 会被呈现以帮助排查问题

故障排查#

连接测试失败

• 验证基础 URL 是否正确且可访问
• 检查测试端点是否存在并拼写正确
• 确保凭据有效且拥有必要权限
• 部分 API 需要特定请求头，请查阅文档

认证无效

• 确认使用了正确的认证类型
• 对于令牌，确保未过期
• 对于基本认证，确认用户名和密码正确
• 检查 API 是否需要额外请求头

请求返回错误

• 查阅 API 文档确认所需参数
• 验证端点路径是否正确
• 确保请求体格式符合预期
• 注意是否有速率限制或配额问题

认证头错误

• 使用 headerName 为 header 类型指定自定义头名称
• 使用 queryParam 为 query 类型指定查询参数名称
• 使用 authScheme 自定义令牌前缀（默认：Bearer）