agentkit-client — AgentKit Python Reference SDK

零第三方依赖（仅使用标准库 urllib / json / os）的 AgentKit 网关参考客户端， 封装 discover → quote → call 流程，并提供只读能力索引与 MCP tools/list 入口。

• 线上网关：https://agentkit.ltd
• 数据采集时间：2026-10-17（端点事实来自公网实测）
• 许可证：MIT
• 要求：Python 3.9+

Open-core 边界：本 SDK 只封装公开的集成协议（检索、报价、调用、MCP 清单）， 不包含、也不暴露任何网关内部实现。

安装

无第三方依赖，无需安装即可从源码目录直接运行；也可将 agentkit/ 包复制进项目。

# 从源码目录使用（pip 不需要安装任何依赖）
python3 examples/quote.py

快速开始

import os
from agentkit import AgentKit

client = AgentKit(
    base_url="https://agentkit.ltd",
    api_key=os.environ.get("AGENTKIT_API_KEY"),  # 仅 call() 需要
)

# 只读：能力索引
idx = client.list_skills()

# 只读：自然语言检索（当前线上可能返回空结果，SDK 优雅降级）
found = client.discover("json")

# 只读：报价 + 输入 schema
q = client.quote("jsonfmt")

# 执行（需要 API key，会发起真实计费调用）
res = client.call("jsonfmt", {"text": '{"a": 1}'})

API key 未在构造函数传入时，客户端自动读取环境变量 AGENTKIT_API_KEY。

API

构造参数

client = AgentKit(
    base_url="https://agentkit.ltd",            # 默认值，可覆盖
    api_key=os.environ.get("AGENTKIT_API_KEY"), # 默认读环境变量
    auth_header=lambda key: f"Bearer {key}",    # 可选，覆盖鉴权头值
    mcp_client_info={"name": "my-agent", "version": "1.0.0"},  # 可选
    timeout=30.0,
)

鉴权头约定（待确认）：call() 默认按 Authorization: Bearer <key> 发送， 这是 2026-10-17 时的默认实现，待与线上网关最终确认；如需改用其它头格式， 通过构造参数 auth_header（字符串或 api_key -> str 可调用对象）覆盖。

调用前若没有任何 key，客户端在本地直接抛出 MissingApiKeyError，不会发出请求。

错误处理

所有非 2xx 响应被规范化为 AgentKitError，属性：

公开错误码：INVALID_KEY、INVALID_QUERY、INTERNAL_ERROR、UNKNOWN_TOOL、 ANONYMOUS_QUOTA_EXCEEDED、INSUFFICIENT_BALANCE、GUARDRAIL_BLOCKED。

from agentkit import AgentKit, AgentKitError

try:
    client.call("jsonfmt", {"text": "{}"})
except AgentKitError as err:
    print(err.error_code, err.http_status, err.retryable, err.detail)

MissingApiKeyError 是 AgentKitError 的子类（error_code: 'MISSING_API_KEY'，本地抛出）。

MCP 说明

mcp_list_tools() 对 POST /mcp 依次发送：

1. JSON-RPC initialize（id=1，protocolVersion: "2025-03-26"，clientInfo 可配置）；
2. JSON-RPC tools/list（id=2）。

请求头固定为 Content-Type: application/json、Accept: application/json, text/event-stream； 响应同时兼容 JSON 与 SSE（data: 行）两种格式。当前网关只暴露 tools 能力， 返回 13 个 hosted 工具，每个含 name、description、inputSchema（与 quote 的 schema 一致）。

示例

只读冒烟（无 key 可跑）：

python3 scripts/smoke.py

离线单元测试（不访问网络）：

python3 -m unittest discover -s tests -v

Open-core 边界声明

本仓库只公开协议契约与参考客户端；网关的执行、配额与密钥管理等内部实现 不在开源范围内。SDK 不内置任何真实密钥，示例一律从 os.environ 读取或使用 占位符 YOUR_API_KEY。

许可证

MIT, Copyright (c) 2026 AgentKit