Metadata-Version: 2.4
Name: agentkit-client
Version: 0.1.0
Summary: Zero-dependency reference client SDK for the AgentKit gateway (discover / quote / call / MCP tools.list)
Author: AgentKit
License-Expression: MIT
Keywords: agentkit,mcp,ai-agent,sdk,reference-client
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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/` 包复制进项目。

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

## 快速开始

```python
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

| 方法 | 端点 | 鉴权 | 说明 |
|---|---|---|---|
| `list_skills()` | `GET /api/skills.json` | 无 | 能力索引，返回 `{ meta, hostedCount, catalogCount, libraryCount, count, skills[] }` |
| `discover(text=None, json=None)` | `GET /api/discover?text=...` | 无 | 自然语言检索；返回规范化的 `{ query, count, results[] }`，空结果不报错 |
| `quote(tool)` | `GET /api/quote?tool=<id>` | 无 | 报价与输入 JSON Schema，返回 `{ tool, name, priceUsd, currency, schema, errorContract, freeTierPerIp }` |
| `call(tool, arguments=None)` | `POST /api/call` | 需要 key | 执行工具；请求体严格为 `{ "tool": id, "arguments": {...} }` |
| `mcp_list_tools()` | `POST /mcp`（initialize → tools/list） | 无 | MCP Streamable HTTP 握手后返回 tools 数组 |

### 构造参数

```python
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`，属性：

| 属性 | 类型 | 说明 |
|---|---|---|
| `http_status` | int | HTTP 状态码；本地错误为 `0` |
| `error_code` | str | 响应体 `error` 字段（如 `INVALID_KEY`） |
| `retryable` | bool | 响应体 `retryable` 字段，指示是否可重试 |
| `detail` | str | 响应体 `detail` 字段 |

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

```python
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 |
|---|---|---|
| `examples/discover.py` | 列出索引 + discover 检索 | 否 |
| `examples/quote.py` | `quote('jsonfmt')` 报价演示 | 否 |
| `examples/mcp.py` | initialize + tools/list 演示 | 否 |
| `examples/call.py` | call 执行演示 | **是，会产生真实计费，无 key 请勿运行** |

只读冒烟（无 key 可跑）：

```bash
python3 scripts/smoke.py
```

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

```bash
python3 -m unittest discover -s tests -v
```

## Open-core 边界声明

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

## 许可证

MIT, Copyright (c) 2026 AgentKit
