agentkit-client 0.1.0__tar.gz

agentkit_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentkit_client-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+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

agentkit_client-0.1.0/README.md

@@ -0,0 +1,142 @@
+# 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

agentkit_client-0.1.0/agentkit/__init__.py

@@ -0,0 +1,7 @@
+"""AgentKit reference client SDK (zero third-party dependencies, stdlib only)."""
+
+from .client import AgentKit
+from .errors import AgentKitError, MissingApiKeyError
+
+__all__ = ["AgentKit", "AgentKitError", "MissingApiKeyError"]
+__version__ = "0.1.0"

agentkit_client-0.1.0/agentkit/client.py

@@ -0,0 +1,263 @@
+"""AgentKit reference client (standard library only: urllib / json / os).
+
+Flow: discover (search the index) -> quote (read price + input schema) -> call (execute).
+Requires Python 3.9+.
+"""
+
+import json
+import os
+from typing import Any, Dict, Optional
+from urllib import request as _urlrequest
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode
+
+from .errors import AgentKitError, MissingApiKeyError
+
+DEFAULT_BASE_URL = "https://agentkit.ltd"
+DEFAULT_MCP_CLIENT_INFO = {"name": "agentkit-python-client", "version": "0.1.0"}
+
+
+def _parse_body(raw: str, content_type: str) -> Dict[str, Any]:
+    """Parse a JSON body or an MCP SSE stream (``data: {...}`` lines)."""
+    if not raw:
+        return {}
+    if "text/event-stream" in content_type.lower():
+        last = None
+        for line in raw.splitlines():
+            line = line.strip()
+            if line.startswith("data:"):
+                payload = line[5:].strip()
+                if payload:
+                    last = payload
+        if last is None:
+            return {}
+        try:
+            parsed = json.loads(last)
+        except (ValueError, TypeError):
+            return {}
+        return parsed if isinstance(parsed, dict) else {}
+    try:
+        parsed = json.loads(raw)
+    except (ValueError, TypeError):
+        return {"raw": raw}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+class AgentKit:
+    """Reference client for the AgentKit gateway (https://agentkit.ltd).
+
+    :param base_url: Gateway base URL, defaults to ``https://agentkit.ltd``.
+    :param api_key: API key; defaults to the ``AGENTKIT_API_KEY`` environment
+        variable. Only :meth:`call` requires it.
+    :param auth_header: Override the Authorization header value sent by
+        :meth:`call`. May be a static string or a callable ``(api_key) -> str``.
+        NOTE: the header convention used here (``Authorization: Bearer <key>``)
+        is the default implementation as of 2026-10-17 and remains to be
+        finalized with the live gateway; override via this parameter if needed.
+    :param mcp_client_info: ``clientInfo`` reported during the MCP initialize
+        handshake.
+    :param timeout: Per-request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: Optional[str] = None,
+        auth_header: Any = None,
+        mcp_client_info: Optional[Dict[str, str]] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.api_key = api_key if api_key is not None else os.environ.get("AGENTKIT_API_KEY", "")
+        self.auth_header = auth_header
+        self.mcp_client_info = {**DEFAULT_MCP_CLIENT_INFO, **(mcp_client_info or {})}
+        self.timeout = timeout
+
+    def _auth_headers(self) -> Dict[str, str]:
+        if not self.api_key:
+            raise MissingApiKeyError()
+        if callable(self.auth_header):
+            value = self.auth_header(self.api_key)
+        elif isinstance(self.auth_header, str) and self.auth_header:
+            value = self.auth_header
+        else:
+            # Default convention (2026-10-17, pending final confirmation with the gateway).
+            value = f"Bearer {self.api_key}"
+        return {"Authorization": value}
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        payload: Optional[Dict[str, Any]] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        data = None
+        headers = {"Accept": "application/json"}
+        if payload is not None:
+            data = json.dumps(payload).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if extra_headers:
+            headers.update(extra_headers)
+
+        req = _urlrequest.Request(url, data=data, headers=headers, method=method)
+        try:
+            with _urlrequest.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read().decode("utf-8", errors="replace")
+                content_type = resp.headers.get("Content-Type", "")
+                return _parse_body(raw, content_type)
+        except HTTPError as exc:
+            try:
+                raw = exc.read().decode("utf-8", errors="replace")
+                body = _parse_body(raw, exc.headers.get("Content-Type", "") if exc.headers else "")
+            finally:
+                exc.close()
+            code = body.get("error") or f"HTTP_{exc.code}"
+            retryable = bool(body.get("retryable", False))
+            detail = body.get("detail") or body.get("message") or ""
+            raise AgentKitError(
+                http_status=exc.code,
+                error_code=code,
+                retryable=retryable,
+                detail=detail,
+            ) from exc
+        except URLError as exc:
+            raise AgentKitError(
+                http_status=0,
+                error_code="NETWORK_ERROR",
+                retryable=True,
+                detail=str(getattr(exc, "reason", exc)),
+            ) from exc
+
+    def list_skills(self) -> Dict[str, Any]:
+        """GET /api/skills.json — read-only capability index.
+
+        :return: Full index: ``{ meta, hostedCount, catalogCount, libraryCount,
+            count, skills[] }``.
+        """
+        return self._request("GET", "/api/skills.json")
+
+    def discover(
+        self,
+        text: Optional[str] = None,
+        json: Any = None,
+    ) -> Dict[str, Any]:
+        """GET /api/discover?text=<query> — natural-language search over the index.
+
+        NOTE: as of 2026-10-17 the live endpoint intermittently returns an empty
+        result set; the SDK always resolves with a normalized
+        ``{ query, count, results: [] }`` shape instead of raising.
+
+        :param text: Natural-language task text.
+        :param json: Structured request sent as the ``json`` query parameter
+            (dicts are serialized to JSON).
+        :return: ``{ query, count, results }``.
+        """
+        params = {}
+        if text:
+            params["text"] = text
+        if json is not None:
+            params["json"] = json if isinstance(json, str) else json.dumps(json, ensure_ascii=False)
+        qs = urlencode(params)
+        path = f"/api/discover?{qs}" if qs else "/api/discover"
+        body = self._request("GET", path)
+        results = body.get("results")
+        return {
+            "query": body.get("query") if body.get("query") is not None else text,
+            "count": body.get("count") if isinstance(body.get("count"), int) else 0,
+            "results": results if isinstance(results, list) else [],
+        }
+
+    def quote(self, tool: str) -> Dict[str, Any]:
+        """GET /api/quote?tool=<id> — price, input schema and error contract.
+
+        :param tool: Tool id (e.g. ``"jsonfmt"``).
+        :return: Quote object: ``{ tool, name, priceUsd, currency, schema,
+            errorContract, freeTierPerIp }``.
+        """
+        if not tool:
+            raise AgentKitError(
+                http_status=0,
+                error_code="INVALID_QUERY",
+                retryable=False,
+                detail="tool id is required",
+            )
+        return self._request("GET", f"/api/quote?tool={quote(tool, safe='')}")
+
+    def call(self, tool: str, arguments: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """POST /api/call — execute a hosted tool. Requires an API key.
+
+        This performs a real billed call on the gateway; do not run it without
+        reading the quote first and confirming the key.
+
+        :param tool: Tool id (e.g. ``"jsonfmt"``).
+        :param arguments: Arguments matching the tool's quote schema.
+        :return: Gateway response body.
+        """
+        if not tool:
+            raise AgentKitError(
+                http_status=0,
+                error_code="INVALID_QUERY",
+                retryable=False,
+                detail="tool id is required",
+            )
+        headers = self._auth_headers()
+        return self._request(
+            "POST",
+            "/api/call",
+            payload={"tool": tool, "arguments": arguments or {}},
+            extra_headers=headers,
+        )
+
+    def mcp_list_tools(self) -> list:
+        """MCP Streamable HTTP handshake over POST /mcp.
+
+        Sends ``initialize`` (id=1) then ``tools/list`` (id=2) and returns the
+        tools array.
+        """
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+        }
+        init = self._request(
+            "POST",
+            "/mcp",
+            payload={
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "initialize",
+                "params": {
+                    "protocolVersion": "2025-03-26",
+                    "capabilities": {},
+                    "clientInfo": self.mcp_client_info,
+                },
+            },
+            extra_headers=headers,
+        )
+        if init.get("error"):
+            err = init["error"]
+            raise AgentKitError(
+                http_status=0,
+                error_code=err.get("code") if isinstance(err, dict) else "MCP_ERROR",
+                retryable=False,
+                detail=err.get("message", "MCP initialize failed") if isinstance(err, dict) else "MCP initialize failed",
+            )
+
+        listed = self._request(
+            "POST",
+            "/mcp",
+            payload={"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
+            extra_headers=headers,
+        )
+        if listed.get("error"):
+            err = listed["error"]
+            raise AgentKitError(
+                http_status=0,
+                error_code=err.get("code") if isinstance(err, dict) else "MCP_ERROR",
+                retryable=False,
+                detail=err.get("message", "MCP tools/list failed") if isinstance(err, dict) else "MCP tools/list failed",
+            )
+        result = listed.get("result") or {}
+        tools = result.get("tools")
+        return tools if isinstance(tools, list) else []

agentkit_client-0.1.0/agentkit/errors.py

@@ -0,0 +1,50 @@
+"""Structured errors raised by the AgentKit Python client.
+
+Gateway failure body shape:
+    {"error": "INVALID_KEY", "retryable": false, "detail": "..."}
+
+Public error codes (see README.md):
+    INVALID_KEY, INVALID_QUERY, INTERNAL_ERROR, UNKNOWN_TOOL,
+    ANONYMOUS_QUOTA_EXCEEDED, INSUFFICIENT_BALANCE, GUARDRAIL_BLOCKED
+"""
+
+
+class AgentKitError(Exception):
+    """Normalized error carrying HTTP status, machine-readable code and retryability."""
+
+    def __init__(
+        self,
+        message: str = "",
+        http_status: int = 0,
+        error_code: str = "UNKNOWN_ERROR",
+        retryable: bool = False,
+        detail: str = "",
+    ) -> None:
+        if not message:
+            message = f"{error_code} (HTTP {http_status}): {detail}".strip()
+        super().__init__(message)
+        self.http_status = http_status
+        self.error_code = error_code
+        self.retryable = bool(retryable)
+        self.detail = detail
+
+
+class MissingApiKeyError(AgentKitError):
+    """Raised locally by ``call()`` before any request when no API key is configured.
+
+    No network request is made in this case.
+    """
+
+    def __init__(self, message: str = "") -> None:
+        if not message:
+            message = (
+                "Missing API key: pass api_key to the AgentKit constructor or set "
+                "the AGENTKIT_API_KEY environment variable before calling call()."
+            )
+        super().__init__(
+            message=message,
+            http_status=0,
+            error_code="MISSING_API_KEY",
+            retryable=False,
+            detail=message,
+        )

agentkit_client-0.1.0/agentkit_client.egg-info/PKG-INFO

@@ -0,0 +1,154 @@
+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

agentkit_client-0.1.0/agentkit_client.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+agentkit/__init__.py
+agentkit/client.py
+agentkit/errors.py
+agentkit_client.egg-info/PKG-INFO
+agentkit_client.egg-info/SOURCES.txt
+agentkit_client.egg-info/dependency_links.txt
+agentkit_client.egg-info/top_level.txt
+tests/test_client.py

agentkit_client-0.1.0/agentkit_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agentkit_client-0.1.0/agentkit_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+agentkit

agentkit_client-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentkit-client"
+version = "0.1.0"
+description = "Zero-dependency reference client SDK for the AgentKit gateway (discover / quote / call / MCP tools.list)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "AgentKit" }]
+keywords = ["agentkit", "mcp", "ai-agent", "sdk", "reference-client"]
+dependencies = []
+
+[tool.setuptools.packages.find]
+include = ["agentkit*"]

agentkit_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agentkit_client-0.1.0/tests/test_client.py

@@ -0,0 +1,165 @@
+"""Offline unit tests for the AgentKit client (unittest + mock, no network).
+
+Run from sdk/python/: python3 -m unittest discover -s tests -v
+"""
+import io
+import json
+import os
+import sys
+import unittest
+from urllib.error import HTTPError
+from unittest import mock
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from agentkit import AgentKit, AgentKitError, MissingApiKeyError  # noqa: E402
+
+
+class FakeResp:
+    def __init__(self, body, content_type="application/json"):
+        self._body = body if isinstance(body, str) else json.dumps(body)
+        self.headers = {"Content-Type": content_type}
+
+    def read(self):
+        return self._body.encode("utf-8")
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        return False
+
+
+def make_http_error(status, body):
+    raw = io.BytesIO(json.dumps(body).encode("utf-8"))
+    return HTTPError("https://agentkit.ltd/api/call", status, "error", {}, raw)
+
+
+class ClientTests(unittest.TestCase):
+    def make_client(self, **kwargs):
+        kwargs.setdefault("base_url", "https://agentkit.ltd")
+        return AgentKit(**kwargs)
+
+    def test_missing_api_key_raises_before_request(self):
+        client = self.make_client(api_key="")
+        with mock.patch("agentkit.client._urlrequest.urlopen") as urlopen:
+            with self.assertRaises(MissingApiKeyError):
+                client.call("jsonfmt", {"text": "{}"})
+            urlopen.assert_not_called()
+
+    def test_call_sends_bearer_header_and_body(self):
+        client = self.make_client(api_key="test-key")
+        captured = {}
+
+        def fake_urlopen(req, timeout=None):
+            captured["req"] = req
+            return FakeResp({"ok": True, "tool": "jsonfmt"})
+
+        with mock.patch("agentkit.client._urlrequest.urlopen", side_effect=fake_urlopen):
+            res = client.call("jsonfmt", {"text": '{"a":1}'})
+
+        req = captured["req"]
+        self.assertEqual(req.get_method(), "POST")
+        self.assertEqual(req.get_header("Authorization"), "Bearer test-key")
+        sent = json.loads(req.data.decode("utf-8"))
+        self.assertEqual(sent, {"tool": "jsonfmt", "arguments": {"text": '{"a":1}'}})
+        self.assertTrue(res["ok"])
+
+    def test_auth_header_override(self):
+        client = self.make_client(api_key="test-key", auth_header="Token test-key")
+        captured = {}
+
+        def fake_urlopen(req, timeout=None):
+            captured["req"] = req
+            return FakeResp({"ok": True})
+
+        with mock.patch("agentkit.client._urlrequest.urlopen", side_effect=fake_urlopen):
+            client.call("jsonfmt", {})
+
+        req = captured["req"]
+        self.assertEqual(req.get_header("Authorization"), "Token test-key")
+
+    def test_auth_header_callable_override(self):
+        client = self.make_client(api_key="test-key", auth_header=lambda k: f"Api-Key {k}")
+        captured = {}
+
+        def fake_urlopen(req, timeout=None):
+            captured["req"] = req
+            return FakeResp({"ok": True})
+
+        with mock.patch("agentkit.client._urlrequest.urlopen", side_effect=fake_urlopen):
+            client.call("jsonfmt", {})
+
+        self.assertEqual(captured["req"].get_header("Authorization"), "Api-Key test-key")
+
+    def test_quote_parses_price(self):
+        body = {
+            "tool": "jsonfmt",
+            "priceUsd": 0.1,
+            "currency": "USD",
+            "schema": {"type": "object", "required": ["text"], "properties": {}},
+        }
+        with mock.patch("agentkit.client._urlrequest.urlopen", return_value=FakeResp(body)):
+            q = self.make_client().quote("jsonfmt")
+        self.assertEqual(q["priceUsd"], 0.1)
+        self.assertIn("text", q["schema"]["required"])
+
+    def test_discover_normalizes_empty_result(self):
+        body = {"query": None, "count": 0, "results": []}
+        with mock.patch("agentkit.client._urlrequest.urlopen", return_value=FakeResp(body)):
+            found = self.make_client().discover("json")
+        self.assertEqual(found["count"], 0)
+        self.assertEqual(found["results"], [])
+
+    def test_http_error_maps_to_agentkit_error(self):
+        err_body = {"error": "INVALID_KEY", "retryable": False, "detail": "API Key 无效"}
+        client = self.make_client(api_key="bad")
+        with mock.patch(
+            "agentkit.client._urlrequest.urlopen",
+            side_effect=make_http_error(401, err_body),
+        ):
+            with self.assertRaises(AgentKitError) as ctx:
+                client.call("jsonfmt", {})
+        self.assertEqual(ctx.exception.http_status, 401)
+        self.assertEqual(ctx.exception.error_code, "INVALID_KEY")
+        self.assertFalse(ctx.exception.retryable)
+        self.assertIn("API Key", ctx.exception.detail)
+
+    def test_mcp_list_tools_initializes_then_lists(self):
+        init_resp = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "result": {
+                "protocolVersion": "2025-03-26",
+                "capabilities": {"tools": {"listChanged": False}},
+                "serverInfo": {"name": "agentkit", "version": "3.0.0"},
+            },
+        }
+        tools = [{"name": f"tool-{i}", "description": "", "inputSchema": {}} for i in range(13)]
+        list_resp = {"jsonrpc": "2.0", "id": 2, "result": {"tools": tools}}
+        calls = []
+
+        def fake_urlopen(req, timeout=None):
+            calls.append(json.loads(req.data.decode("utf-8")))
+            return FakeResp(init_resp if len(calls) == 1 else list_resp)
+
+        with mock.patch("agentkit.client._urlrequest.urlopen", side_effect=fake_urlopen):
+            result = self.make_client().mcp_list_tools()
+
+        self.assertEqual(len(result), 13)
+        self.assertEqual(calls[0]["method"], "initialize")
+        self.assertEqual(calls[0]["params"]["protocolVersion"], "2025-03-26")
+        self.assertEqual(calls[1]["method"], "tools/list")
+
+    def test_sse_body_is_parsed(self):
+        sse = 'event: message\ndata: {"jsonrpc":"2.0","id":2,"result":{"tools":[]}}\n\n'
+        with mock.patch(
+            "agentkit.client._urlrequest.urlopen",
+            return_value=FakeResp(sse, content_type="text/event-stream"),
+        ):
+            result = self.make_client().mcp_list_tools()
+        self.assertEqual(result, [])
+
+
+if __name__ == "__main__":
+    unittest.main()