代理即工具

JamJet 允许你将任何代理封装为工作流中的可调用工具。三种调用模式涵盖不同的使用场景——从快速查询到长时运行分析再到多轮对话。

三种模式

同步模式

单次请求,单次响应。最适合快速、无状态的操作。

graph.add_agent_tool("classifier",
    agent="https://classifier-agent.example.com",
    mode="sync",
    timeout_ms=5000,
)

向 /tasks/send 发送请求并将完整响应作为节点输出返回。

流式模式

增量式 NDJSON 处理并实时发出事件。最适合需要进度可见性、预算控制和提前终止的长时运行代理。

graph.add_agent_tool("researcher",
    agent="https://research-agent.example.com",
    mode="streaming",
    budget={"max_cost_usd": 0.50},
    streaming={"idle_timeout_secs": 30},
)

向 /tasks/sendSubscribe 发送请求并增量式处理 NDJSON 流:

• 实时事件 — 每个数据块在到达时立即发送到状态后端,而非在结束时批量处理
• 空闲超时 — 如果在 idle_timeout_secs(默认 30 秒)内没有数据到达,流将被终止
• 预算保护 — 当从数据块累积的 cost_usd 超过 max_cost_usd 时,流将停止
• A2A 取消 — 在提前终止时(预算或超时),会尽力向远程代理发送 tasks/cancel 请求
• 保留部分结果 — 已发出的数据块永远不会丢失,即使在失败时也是如此

对话模式

用于迭代优化的多轮交互。协调器发送输入,读取响应,并将其作为下一轮的输入反馈。

graph.add_agent_tool("editor",
    agent="https://editor-agent.example.com",
    mode={"conversational": {"max_turns": 5}},
)

循环向 /tasks/send 发送请求。当代理响应 status: "completed" 或达到 max_turns 时停止。

流式配置

对于流式模式,每个数据块的空闲超时替代整体 HTTP 超时。客户端构建时没有全局超时,因此有活跃数据的长时运行流不会被过早终止。

事件

代理工具会向事件日志发出结构化事件：

每个事件都包含 timestamp_ms 以提供精确的时间信息。进度事件还包括 chunk_index 和 accumulated_cost_usd。

错误处理

硬性故障（超时、网络错误）会导致节点失败，以便工作流可以重试或处理错误。预算超限也被视为失败。

协议解析

代理 URI 决定使用的协议：

示例

请参阅 agent-as-tool 示例，了解使用所有三种模式的完整工作流。