> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> AgentEye Python SDK 文档。

AgentEye Python SDK 为您提供对 Agent 行为的完整可见性（包括每次 Agent 运行、工具调用、模型请求、Hook 以及人工干预），帮助您调试、审计和评估它们。SDK 通过将结构化事件写入本地 JSONL 文件来对 Agent 代码进行埋点；采集器守护进程会自动拾取这些文件并将其上报至平台。

***

## 安装

使用您的 `AGENTEYE_TOKEN` 从 GitHub Releases 下载 wheel 包。如果您还没有 Token，请参阅 [GitHub Token 设置](/zh/agenteye/github-token) 了解设置步骤和所需权限。

**使用 `gh` CLI + pip：**

```bash theme={null}
VERSION=0.0.1b9
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "python-sdk/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-*.whl'
pip install "agenteye-${VERSION}-py3-none-any.whl"
```

**使用 `gh` CLI + uv：**

```bash theme={null}
VERSION=0.0.1b9
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "python-sdk/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-*.whl'
uv add "./agenteye-${VERSION}-py3-none-any.whl"
```

**使用 curl（无需 `gh` CLI）：**

```bash theme={null}
VERSION=0.0.1b9
curl -fsSL \
  -H "Authorization: Bearer $AGENTEYE_TOKEN" \
  -L \
  "https://github.com/agenteye-enterprise/releases/releases/download/python-sdk%2Fv${VERSION}/agenteye-${VERSION}-py3-none-any.whl" \
  -o "agenteye-${VERSION}-py3-none-any.whl"
pip install "agenteye-${VERSION}-py3-none-any.whl"
```

***

## 快速开始

```python theme={null}
import agenteye

agenteye.configure(environment="production")

agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    input={"query": "latest AI research"},
)

agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    output={"results": ["..."]},
)

agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")
```

***

## configure()

```python theme={null}
agenteye.configure(
    base_dir=None,           # Path | str | None。默认值：$AGENTEYE_HOME 或 ~/.agenteye
    flush_interval=0.5,      # float，刷新周期间隔，单位：秒
    environment=None,        # str | None。部署环境标签
)
```

请在任何 `event.*` 调用之前调用一次。可以省略；默认配置开箱即用。所有参数均为仅限关键字参数，请按上方示例以命名方式传入。

当 `base_dir` 为 `None`（默认值）时，SDK 会优先读取 `$AGENTEYE_HOME`（若已设置），否则回退到 `~/.agenteye`。此行为与采集器自身的路径解析逻辑一致，因此只需配置一个 `AGENTEYE_HOME` 环境变量，即可同时为 SDK 和采集器指定共享事件缓冲目录，这在 sidecar / 单 Pod 部署场景中尤为重要——两个进程必须使用相同的缓冲路径。

***

## 环境

为每个事件打上部署环境标签（如 `production`、`staging`、`qa`、`canary` 等）。只需设置一次，SDK 会自动将其附加到每个事件上。

**方式一：通过 `configure()` 设置：**

```python theme={null}
agenteye.configure(environment="production")
```

**方式二：通过环境变量设置：**

```bash theme={null}
export AGENTEYE_ENVIRONMENT=production
```

**优先级：** `configure(environment=...)` 优先于环境变量。若两者均未设置，则默认为 `"dev"`。

环境值在仪表盘中作为一级筛选条件显示，并在服务器端以索引列形式存储，以支持快速查询。

**限制：** 环境值**不得包含字面逗号 `,`**。仪表盘筛选器在传输时使用逗号分隔的多选格式（`?environment=prod,staging`），因此名为 `prod,blue` 的环境值会被拆分为两个独立值。包含逗号的环境值在数据摄入时将被拒绝。

***

## 事件参考

所有事件方法均需要以下两个字段：

| 字段           | 类型    | 说明                 |
| ------------ | ----- | ------------------ |
| `session_id` | `str` | 标识顶层 Agent 运行实例    |
| `agent_id`   | `str` | 标识会话中发出事件的具体 Agent |

所有方法还接受任意 `**kwargs` 用于自定义元数据（参见[自定义字段](#custom-fields)）。

***

### `event.agent_start()`

Agent 开始工作时触发。

```python theme={null}
agenteye.event.agent_start(
    session_id="run-001",
    agent_id="planner",
    goal="answer user query",   # str | None
    parent_id=None,             # str | None - 嵌套 Agent 的父 agent_id
)
```

***

### `event.agent_end()`

Agent 完成工作时触发。

```python theme={null}
agenteye.event.agent_end(
    session_id="run-001",
    agent_id="planner",
    outcome="success",          # str | None
    summary="Answered query",   # str | None
)
```

***

### `event.tool_use()`

Agent 调用工具时触发。与 `tool_result` 配对使用；SDK 会自动计算 `duration_ms`。

```python theme={null}
agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",     # str，必填
    tool_call_id="toolu_01",    # str，必填 - 与对应 tool_result 的关联键
    input={"query": "..."},     # dict | None
)
```

***

### `event.tool_result()`

工具返回结果时触发。通过 `tool_call_id` 与 `tool_use` 关联。

```python theme={null}
agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",        # 必须与之前的 tool_use 匹配
    output={"results": ["..."]},    # Any | None
    error=None,                     # str | None - 工具抛出异常时设置
    # duration_ms 由 SDK 自动计算，请勿手动传入
)
```

***

### `event.model_request()`

向 LLM 发送提示词之前触发。

```python theme={null}
agenteye.event.model_request(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None
    messages=[                   # list[dict] | None - 对话轮次
        {"role": "user", "content": "..."},
    ],
    system="You are helpful.",   # Any | None - 字符串或内容块列表
    tools=[                      # list[dict] | None - 提供给模型的工具 schema
        {"name": "search", "input_schema": {"type": "object"}},
    ],
)
```

`messages` 条目的 `content` 字段支持普通字符串或 Anthropic 风格的内容块列表。采样参数（`temperature`、`max_tokens` 等）可作为额外的 kwargs 传入。

***

### `event.model_response()`

LLM 返回响应时触发。

```python theme={null}
agenteye.event.model_response(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None
    stop_reason="end_turn",     # str | None
    input_tokens=1024,          # int | None
    output_tokens=256,          # int | None
    content=[                    # Any | None - 字符串或内容块列表
        {"type": "text", "text": "..."},
    ],
    role="assistant",            # str | None
)
```

`content` 支持普通字符串（通用提供商）或 Anthropic 风格内容块列表。工具调用以 `{"type": "tool_use", ...}` 块的形式嵌入在 `content` 中，不单独设置 `tool_calls` 字段。

***

### `event.hook_triggered()`

Hook 触发时触发。与 `hook_completed` 配对使用；SDK 会自动计算 `duration_ms`。

```python theme={null}
agenteye.event.hook_triggered(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",   # str，必填
    hook_id="hook-abc",         # str，必填 - 关联键
    trigger_event="tool_use",   # str | None
    input={"tool": "search"},   # Any | None
)
```

***

### `event.hook_completed()`

Hook 执行完成时触发。通过 `hook_id` 与 `hook_triggered` 关联。

```python theme={null}
agenteye.event.hook_completed(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",
    hook_id="hook-abc",         # 必须与之前的 hook_triggered 匹配
    outcome="allow",            # str | None
    output=None,                # Any | None
    error=None,                 # str | None
    # duration_ms 由 SDK 自动计算，请勿手动传入
)
```

***

### `event.error()`

发生未处理错误时触发。

```python theme={null}
agenteye.event.error(
    session_id="run-001",
    agent_id="planner",
    error_type="TimeoutError",  # str，必填
    message="timed out",        # str，必填
    traceback="Traceback...",   # str | None
)
```

***

## 人机协作事件

人机协作事件让您能够监控人员介入 Agent 执行流程的关键时刻（等待审批、提供输入、暂停或停止 Agent）。通过这些事件，您可以衡量人类响应所需的时长（SDK 会自动为配对事件计算 `duration_ms`），审计是谁暂停或中断了 Agent，并构建在仪表盘中呈现的审批与监督工作流。

### `event.human_wait()`

Agent 暂停执行并等待人工输入时触发。与 `human_input` 配对使用；SDK 会自动计算 `duration_ms`（即人类响应所用时长）。

```python theme={null}
agenteye.event.human_wait(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",                          # str，必填 - 与对应 human_input 的关联键
    prompt="Do you approve this action?",        # str | None - 向人类展示的问题
    options=["approve", "reject", "defer"],      # list[str] | None - 呈现给人类的选项
    reason="approval_required",                  # str | None - Agent 等待的原因
)
```

### `event.human_input()`

人类提供输入且 Agent 恢复执行时触发。通过 `input_id` 与 `human_wait` 关联。`duration_ms` 由 SDK 自动计算，调用方不得手动传入。

```python theme={null}
agenteye.event.human_input(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",    # str，必填 - 必须与之前的 human_wait 匹配
    response="approve",    # str | None - 人类的回答（自由文本或所选选项）
    # duration_ms 由 SDK 自动计算，请勿手动传入
)
```

### `event.human_pause()`

人类主动暂停 Agent 时触发（例如通过仪表盘控件）。Agent 被挂起但未终止。

```python theme={null}
agenteye.event.human_pause(
    session_id="run-001",
    agent_id="planner",
    reason="user_requested",  # str | None
    user_id="usr_42",         # str | None - 执行暂停操作的用户
)
```

### `event.human_interrupt()`

人类在 Agent 执行过程中主动停止 Agent 时触发。与 `human_pause` 不同，此操作会终止 Agent 的工作，而非挂起。

```python theme={null}
agenteye.event.human_interrupt(
    session_id="run-001",
    agent_id="planner",
    reason="output_incorrect",       # str | None
    user_id="usr_42",                # str | None - 执行中断操作的用户
    at_step="tool_use:web_search",   # str | None - Agent 被停止时正在执行的操作
)
```

***

## 自定义字段

任何额外的关键字参数都会附加到事件的标准字段之后：

```python theme={null}
agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="db_query",
    tool_call_id="toolu_02",
    tenant_id="acme",           # 自定义字段
    region="us-east-1",         # 自定义字段
)
```

`timestamp`、`type` 和 `environment` 为保留字段，若将其作为自定义字段传入，将抛出 `ValueError`（`Reserved field names cannot be used as custom fields: [...]`）。`session_id` 和 `agent_id` 是每个事件方法的必填参数，不能二次传入；若重复传入，Python 会抛出 `TypeError`。请通过 `configure(environment=...)` 或 `AGENTEYE_ENVIRONMENT` 环境变量来设置环境值。

***

## 事件写入机制

事件在进程内缓冲，并每隔 `flush_interval` 秒（默认 500 毫秒）刷新到磁盘。每次刷新写入一个 JSONL 文件：

```
~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl
```

采集器会监视该目录并自动上传文件。您无需手动管理这些文件。