AgentGrid Python SDK

AgentGrid Python SDK v1 提供面向 Runtime 的高层调用接口，主路径围绕以下 API：

• from agentgrid import AgentGridProfile
• runtime.invoke()
• runtime.create_runtime()/update_runtime()/delete_runtime()/get_runtime()/list_runtimes()
• runtime_session()

Python 版本要求

• Python >=3.10

安装

pip

pip install jdcloud-agentgrid

uv（下游项目）

uv add jdcloud-agentgrid
uv sync

SDK 默认配置文件（agentgrid.yaml）

get_sdk_default_config() 会自动尝试读取入口脚本同级的 agentgrid.yaml。

• 查找规则固定为：Path(sys.argv[0]).resolve().parent / "agentgrid.yaml"
• 文件不存在：忽略并回退到 SDK 内置默认配置
• 仅识别 basic 节点，且字段必须是 AgentGridConfig 已定义字段

最小示例：

basic:
  region: cn-north-1
  endpoint: https://agentgrid.jdcloud-api.com
  data_endpoint: https://agentgrid-api-cn-north-1.jdcloud.com
  timeout: 30
  connect_timeout: 5
  read_timeout: 30
  max_retries: 2
  user_agent_extra: demo-app/1.0

例如入口脚本位于 ./examples/run.py，则配置文件应放在 ./examples/agentgrid.yaml。

最小示例（Quick Start）

显式 auth（兼容旧用法）：

from agentgrid import AgentGridProfile, runtime_session

profile = AgentGridProfile(
    region="cn-north-1",
    data_endpoint="https://agentgrid-api-cn-north-1.jdcloud.com",  # 可选：默认就是该地址
)

with runtime_session("cn-north-1", "your-runtime-id", profile=profile) as runtime:
    resp = runtime.invoke(
        {"text": "你好，AgentGrid"},
        api_key="your-runtime-api-key",
    )

print(resp.get("output_text"))
print(resp.get("request_id"), resp.get("trace_id"))

默认 AK/SK 凭证链（无需显式 auth）：

from agentgrid import AgentGridProfile

profile = AgentGridProfile(region="cn-north-1")

当未显式传入 auth 时，AK/SK 优先级固定为：

1. access_key/secret_key 构造参数
2. JDCLOUD_ACCESS_KEY/JDCLOUD_SECRET_KEY
3. ~/.jdcloud/credentials 的 [default]（access_key_id/secret_access_key）

任一来源出现半配置（仅 AK 或仅 SK）会立即报错并终止降级。

支持的认证方式（v1）

• ApiKeyAuthProvider
• JdcloudAkskAuthProvider

v1 仅支持以上两种认证方式。

Runtime 与会话示例

统一调用（自动 JSON/SSE 分流）：

with runtime_session("cn-north-1", "rt-template-001", profile=profile) as runtime:
    result = runtime.invoke(
        {"text": "请总结这段文本"},
        api_key="your-runtime-api-key",
        metadata={"scene": "demo"},
    )

if isinstance(result, dict):
    print(result.get("output_text"))
else:
    for event in result:
        if event.type == "text_delta" and event.text:
            print(event.text, end="", flush=True)

使用 runtime_session()：

from agentgrid import runtime_session

with runtime_session("cn-north-1", "chat-001", profile=profile) as runtime:
    resp = runtime.invoke("会话内调用", api_key="your-runtime-api-key")
    print(resp.get("session_id"))

# 退出上下文时仅记录 end_session 日志，不执行显式网络清理

类型模型（v1）

• runtime.invoke() 按响应 Content-Type 自动返回：
  • JSON：dict
  • SSE：可同步迭代 StreamResponse
• StreamEvent 统一字段：type、text、data、raw

异常与排障

统一异常基类：AgentGridError。

主要子类：

• AgentGridAuthenticationError
• AgentGridAuthorizationError
• AgentGridRateLimitError
• AgentGridTimeoutError
• AgentGridTransportError
• AgentGridStreamError
• AgentGridServerError

异常对象稳定暴露诊断字段：code、request_id、retryable。

控制口与数据口边界（务必注意）：

• 控制口接口（create/update/delete/get/list）仅支持 AK/SK，使用 API Key 会抛出 AgentGridAuthenticationError(code="AUTHENTICATION_REQUIRED")
• 数据口接口（invoke）本期强制 API Key；优先级：请求级 api_key > agentgrid.yaml 的 runtime.api_key