自定义 Agent

本页介绍每个配置项、方法和字段的作用。如果你是第一次接入，请先阅读入门指南——本页面仅供查阅参考。

自定义 Agent 指南

安装、埋点、事件方法、完整示例及常见问题。

使用框架？

LangChain、CrewAI、LlamaIndex 和 Pydantic AI 只需一次调用即可完成自动埋点。

需要 Python 3.10 或更高版本，无运行时依赖。

安装

pip install failproofai-sdk

包名为 failproofai-sdk，在 Python 中以 failproofai_sdk 导入。failproofai-sdk[langgraph] 等框架扩展会同时安装对应框架本身；适配器始终包含在基础安装包中。

连接 Failproof 守护进程

控制台
CLI

前往 Admin → Keys，创建一个具有 events:add 权限的密钥。
在 Agent 所在机器上将 Failproof 守护进程连接到 Cloud。
运行一次已埋点的会话，然后在 Observe → Events 下找到其确切 ID。
前往 Observe → Sessions，选择相同的环境，打开重建后的追踪记录。

将 events:add 密钥读入 Shell。read -s 通过不回显的提示符输入，确保密钥不会出现在命令行或 Shell 历史记录中：

read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN

然后完成机器配置并验证连接状态：

failproofai config
failproofai config --status

配置

import failproofai_sdk

failproofai_sdk.configure(
    base_dir=None,
    flush_interval=0.5,
    environment="production",
)

参数	说明
`environment`	每个事件上的环境标签，如 `production`、`staging`、`prod-eu`，默认为 `dev`。
`flush_interval`	后台线程写入磁盘的频率，单位为秒，默认为 `0.5`。
`base_dir`	写入目录，默认为守护进程的 spool 目录，除非有特殊需求，否则保持默认即可。

也可通过环境变量进行配置：

变量	说明
`AGENTEYE_ENVIRONMENT`	无需修改代码即可设置 `environment`，适用于环境标签属于部署配置而非应用代码的场景。`configure()` 参数优先级高于该变量。
`FAILPROOFAI_HOME`	移动存放 spool 的 Failproof AI 根目录。
`FAILPROOFAI_SDK_STRICT`	设为 `1` 时，埋点错误将抛出异常而非仅记录日志。
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	设为 `1` 时，框架兼容性问题将抛出异常而非仅发出警告后继续运行。

environment 中不能包含逗号。 数据摄取服务会以逗号分割该字段来构建过滤器，标签中含有逗号的事件会被直接丢弃，导致整次运行无声无息地消失。请使用 prod-eu，而非 prod,eu。configure(environment="prod,eu") 会立即抛出异常，方便你及时发现问题。AGENTEYE_ENVIRONMENT 无法抛出异常（因为没有调用方），所以它会警告一次并回退到 dev。

事件先在内存中排队，每隔 flush_interval 秒由后台线程写入，解释器退出时执行最终刷写。进程被强制终止时，尚未写入的事件将会丢失。

身份标识

每个事件都归属于一个会话和一个 agent。作用域会自动填充两者，因此通常无需手动传入：

with failproofai_sdk.session():
    with failproofai_sdk.agent("planner"):
        failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1")

显式传入 session_id 或 agent_id 也完全有效，且优先级更高。如果既没有绑定作用域，也没有手动传入，调用将抛出 TypeError，而不是发出一个 Cloud 会静默丢弃的事件。

身份标识基于上下文变量传递，会自动跟随 asyncio 任务，但不会跟随新线程——请使用 failproofai_sdk.propagate() 包装工作线程，否则其事件将无法关联到对应会话。

事件目录

共 15 个方法，大多数成对出现——调用开始方法，再调用结束方法，SDK 会自动计算两者之间的耗时。

	开始	结束
Agent	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
模型	`model_request`	`model_response`
工具	`tool_use`	`tool_result`
Hook	`hook_triggered`	`hook_completed`
人工	`human_wait`	`human_input`

另有三个独立方法：error、human_pause、human_interrupt。

每个方法的完整字段说明

每个方法同样接受 session_id 和 agent_id 参数，由作用域自动填充。值为 None 的字段会被丢弃，不会以 JSON null 形式发送；所有方法均返回 None。

方法	必填	可选
`agent_start`	—	`goal`, `parent_id`
`agent_end`	—	`outcome`, `summary`
`agent_pause`	`pause_id`	`reason`, `user_id`
`agent_resume`	`pause_id`	`reason`, `user_id`
`model_request`	—	`model`, `messages`, `system`, `tools`, `request_id`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`, `request_id`, `duration_ms`
`tool_use`	`tool_name`, `tool_call_id`	`input`
`tool_result`	`tool_name`, `tool_call_id`	`output`, `error`
`hook_triggered`	`hook_name`, `hook_id`	`trigger_event`, `input`
`hook_completed`	`hook_name`, `hook_id`	`outcome`, `output`, `error`
`error`	`error_type`, `message`	`traceback`
`human_wait`	`input_id`	`prompt`, `options`, `reason`
`human_input`	`input_id`	`response`
`human_pause`	—	`reason`, `user_id`
`human_interrupt`	—	`reason`, `user_id`, `at_step`

要将一次运行标记为失败，outcome 必须是以下值之一：failed、error、timeout 或 rejected。其他任何值——包括容易写错的 "failure"——都会被视为成功。

配对与耗时

一条规则：结束事件必须与其对应的开始事件使用相同的 ID。 这是配对的依据，也是 SDK 计算耗时的方式。

配对	匹配字段
`tool_use` → `tool_result`	`tool_call_id`
`hook_triggered` → `hook_completed`	`hook_id`
`agent_pause` → `agent_resume`	`pause_id`
`human_wait` → `human_input`	`input_id`
`model_request` → `model_response`	`request_id`

不要自行传入 duration_ms。 SDK 会自动测量，手动传入会抛出 ValueError。唯一的例外是 model_response——只有你才知道真实的 provider 延迟。请传入整数毫秒值，浮点数会导致抛出异常，因为该字段是 32 位整数，传入浮点数会导致数据丢失。

边界情况

ID 只需在同类事件、同一会话内唯一。 一个工具调用和一个 hook 可以共用同一个 ID；同时运行的两个会话可以复用相同的 ID 而不会发生冲突。
ID 不限定于某个 agent 的作用域。 在一个 agent 下打开、在另一个 agent 下关闭的配对仍然可以匹配——这在多 agent 代码中是正常情况。
request_id 可选，但推荐填写。 不填时，模型事件按到达顺序配对，同一 agent 内的两个并发调用可能会错误配对。
跨进程的配对在 Cloud 中仍然可以匹配，但 SDK 无法计算耗时——因为没有任何一个进程同时看到了两半。
最多同时等待 10,000 个待配对的开始事件。 超出后最旧的会被丢弃，防止内存泄漏无限增长。

自定义字段

额外传入的关键字参数会随事件一起存储：

failproofai_sdk.event.tool_use(
    tool_name="search", tool_call_id="c1",
    fw_tenant="acme", fw_region="eu-west-1",     # 自定义字段
)

如果希望后续能够查询这些字段，建议使用 JSON 兼容类型。其他类型——UUID、datetime、Decimal、set、bytes、模型对象等——将以字符串形式存储。

为自定义字段名添加前缀。 额外字段最后应用，因此名为 model、tool_name 或 outcome 的字段会静默覆盖真实字段。框架适配器使用 fw_ 前缀；采用相同做法可避免任何冲突。这也是为什么拼写错误的可选字段不会报错——它只会变成一个新的自定义字段。如果 Cloud 中某个标准字段缺失，请先检查拼写。

以下五个字段名为保留字，会被直接拒绝：timestamp、session_id、agent_id、type、environment。

数据投递与验证

控制台
CLI

在 Observe → Events 中，先确认存在 agent_start 事件，最后存在 agent_end 事件。然后打开 Observe → Sessions，确认模型、工具、人工、hook 和错误事件按预期顺序出现。排查问题时以 session ID 作为主要索引。

failproofai flush --wait --timeout 60
failproofai config --status
fp sessions --since 1h --env production --session-id <session-id>
fp events --since 1h --session-id <session-id> --full

如果 Cloud 中没有数据，请检查 $FAILPROOFAI_HOME/custom-agents/events，否则检查 ~/.failproofai/custom-agents/events。JSONL 文件的存在可证明 SDK 已成功发出事件；spool 持续增大说明问题在守护进程配置或数据投递环节；spool 为空则说明问题在埋点或进程生命周期管理上。

仅在守护进程停止时才检查 spool。守护进程运行期间，它会在毫秒内收集并删除每批数据，因此目录列表会与收集器产生竞争，显示的事件数量将远少于实际发出的数量。

在自定义运行时中防止故障

通过审计发现和关联追踪来定义不安全操作、所需证据及预期响应。自定义执行集成必须在操作执行前将其暴露出来，将其结构化输入传递给策略引擎，并执行 allow、instruct 或 deny 决策结果。联系 Failproof AI，我们将协助你将运行时的模型、工具和生命周期边界映射到策略 hook，并与你共同验证集成的正确性。

Connect your agents

Reference

自定义 Agent 指南

使用框架？

安装

连接 Failproof 守护进程

配置

身份标识

事件目录

配对与耗时

自定义字段

数据投递与验证

在自定义运行时中防止故障

自定义 Agent 指南

使用框架？

​安装

​连接 Failproof 守护进程

​配置

​身份标识

​事件目录

​配对与耗时

​自定义字段

​数据投递与验证

​在自定义运行时中防止故障

安装

连接 Failproof 守护进程

配置

身份标识

事件目录

配对与耗时

自定义字段

数据投递与验证

在自定义运行时中防止故障