Metadata-Version: 2.4
Name: jdcloud_agentgrid
Version: 0.1.5
Summary: AgentGrid Python SDK for JDCloud AgentGrid Runtime
Project-URL: Homepage, https://github.com/agentgrid/agentgrid-python
Project-URL: Repository, https://github.com/agentgrid/agentgrid-python
Author: AgentGrid SDK Team
Requires-Python: >=3.10
Requires-Dist: jdcloud-sdk>=1.6.314
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: starlette>=0.37.2
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: langchain-openrouter>=0.2.1; extra == 'dev'
Requires-Dist: langchain>=0.3.28; extra == 'dev'
Requires-Dist: playwright>=1.52.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install jdcloud-agentgrid
```

### uv（下游项目）

```bash
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` 已定义字段

最小示例：

```yaml
basic:
  region: cn-north-1
  endpoint: https://agentgrid.jdcloud-api.com
  data_endpoint: https://agentgrid-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`（兼容旧用法）：

```python
from agentgrid import AgentGridProfile, runtime_session

profile = AgentGridProfile(
    region="cn-north-1",
    data_endpoint="https://agentgrid-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`）：

```python
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 分流）：

```python
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()`：

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