>_我的博客
$ cd ../blog
# markdown

高级 Agent 能力指南

// HITL、Checkpoint 与 Handoff 的接入方式、配置示例,以及当前实现的生产环境边界。

高级 Agent 能力指南

本文覆盖 HITL、Checkpoint 与 Handoff 的当前接入方式。

状态:当前实现指南。HTTP 应用优先使用 HarnessBuilder 配置驱动路径;Manager 级 API 适用于测试和组件理解。

能力状态

能力 Runtime 接入 存储/边界
HITL SDK 原生 needs_approval、interruptions、RunState 恢复 审批请求当前保存在进程内
Checkpoint capability 在 run 前/后保存 AgentState 摘要 当前仅进程内;不是 SDK RunState 仓库
Handoff SDK 原生 Agent.handoffs 环境配置提供静态目标,使用当前模型

HITL

启用并指定需要审批的已注册工具:

HITL_ENABLED=true
HITL_APPROVAL_TIMEOUT=300
HITL_REQUIRE_APPROVAL_TOOLS=get_weather
HITL_AUTO_APPROVE_TOOLS=

HarnessBuilder 将策略应用到 ToolRegistry;Runtime 构建 SDK 工具时设置 needs_approval=True。

请求示例:

curl -X POST http://localhost:8080/chat \
  -H 'Content-Type: application/json' \
  -d '{"query":"请查询北京天气。","sessionId":"hitl-demo","userId":"demo-user"}'

如果 SDK 中断,SSE 流中的 end 事件 data 包含:

{
  "protocol": {"sessionId": "hitl-demo", "turnId": "turn_xxx"},
  "interrupted": true,
  "interruptions": [{"id": "approval-id", "sdk_interruption_index": 0}],
  "runState": {},
  "model": "gpt-4o-mini"
}

恢复时提交响应中的状态与决定:

curl -X POST http://localhost:8080/chat/resume/stream \
  -H 'Content-Type: application/json' \
  -d '{
    "session_id":"hitl-demo",
    "message":"请查询北京天气。",
    "model":"gpt-4o-mini",
    "run_state": {},
    "approval_request_id":"approval-id",
    "interruption_index":0,
    "approved":true
  }'

实际运行可使用:

venv/bin/python examples/hitl_resume.py --approve --message "请查询北京天气。"

生产限制:当前审批请求和匹配状态由进程内 ApprovalManager 保管,调用方回传 SDK state;尚未提供持久化、审计、幂等和跨实例恢复。

Checkpoint

启用 Runtime 的运行边界快照:

CHECKPOINT_ENABLED=true
CHECKPOINT_AUTO_SAVE=true
CHECKPOINT_MAX_CHECKPOINTS=10

当前 capability 在一次完整运行之前与之后保存摘要。它不在每个工具调用后自动创建可恢复的 SDK 执行状态,也不能替代 HITL 的 run_state 保存。

组件级调用:

from src.capabilities.advanced_agents import AgentState, CheckpointConfig, CheckpointManager

manager = CheckpointManager(
    CheckpointConfig(enabled=True, max_checkpoints=10, auto_save=True)
)
state = AgentState(
    session_id="session-001",
    conversation_history=[],
    current_model="gpt-4o-mini",
    tool_calls=[],
    context={"user_id": "user-001"},
)
checkpoint_id = await manager.save("session-001", state, "开始")
restored = await manager.restore(checkpoint_id)

Handoff

推荐通过环境配置静态目标:

HANDOFF_ENABLED=true
HANDOFF_AGENTS_JSON={"billing":{"description":"处理账单问题","instructions":"只处理账单相关请求。"},"support":{"description":"处理技术问题","instructions":"只处理技术支持请求。"}}

在每次 Runtime 构建主 Agent 时,HandoffManager.build_configured_handoffs() 将启用的目标转换为 SDK Agent,并作为 handoffs 传入主 Agent。当前配置只覆盖目标名称、描述、指令与 enabled 标识;不声明目标专属工具和动态路由策略。

组件测试中也可直接使用 manager:

from src.capabilities.advanced_agents import HandoffConfig, HandoffManager

manager = HandoffManager(
    HandoffConfig(
        enabled=True,
        agents={"billing": {"description": "处理账单", "instructions": "只处理账单。"}},
    )
)
targets = manager.build_configured_handoffs(sdk_model)

测试与示例

venv/bin/python -m pytest tests/unit/test_hitl_native_sdk.py \
  tests/unit/test_agent_runtime_resume.py \
  tests/unit/test_handoff_native_sdk.py \
  tests/unit/test_checkpoint_capability.py -q

venv/bin/python examples/handoff.py

相关文档

  • 架构设计(docs/design/ARCHITECTURE_DESIGN.md)
  • AgentOrchestrator 使用指南(docs/usage/AGENT_ORCHESTRATOR_USAGE.md)