Haystack 实验版 Agent 组件全解析：工具调用循环与 Human-in-the-Loop 确认策略

Haystack 实验版 Agent 组件全解析工具调用循环与 Human-in-the-Loop 确认策略【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack本指南围绕 Haystack 文档仓库中docs-website/reference_versioned_docs/version-2.18/experiments-api/experimental_agents_api.md记录的实验性 Agents API 展开讲解 provider 无关的工具型 Agent 组件haystack_experimental.components.agents.Agent如何驱动消息处理 工具调用 退出条件的循环以及如何借助 Human-in-the-LoopHITL确认策略为高风险工具注入人工把关。读完本文你将掌握 Agent 的完整构造参数与运行参数、退出条件机制、AlwaysAskPolicy/NeverAskPolicy/SimpleConsoleUI等确认策略的搭配用法以及基于快照的断点式人工确认BreakpointConfirmationStrategy的实现原理文末还会对照当前主仓库中 Agent 实现 与 HITL 模块 的源码与测试说明这一实验 API 的演进脉络。Agentprovider 无关的工具型智能体Agent是一个 Haystack 组件实现了使用工具tool-using的智能体其底层 LLM 可以是任意支持工具调用的聊天生成器ChatGenerator因此天然 provider 无关——只要聊天生成器的run方法接受tools参数就可以驱动 Agent。它的核心运行逻辑是一个循环把messagesChatMessage列表交给聊天生成器若模型返回带工具调用的消息则逐个执行工具把工具结果写回对话历史再次交给模型直到满足**退出条件exit condition**才返回。退出条件可以由两条路径触发模型直接输出一段纯文本回复没有工具调用或模型调用了某个被指定为退出条件的工具。多个退出条件可以同时指定。值得注意的是不给 Agent 配置任何工具时它就退化为一个 ChatGenerator——生成一次回复后立即退出。从文档注释看这个实验类是在 Haystack 既有Agent组件基础上扩展而来额外增加了human-in-the-loop 确认策略confirmation_strategies支持它同时还支持运行时断点break_point、执行快照snapshot、聊天消息存储chat_message_store与记忆存储memory_store是一套面向生产编排能力的完整实验 API。在当前主仓库中Agent 的核心循环实现位于 haystack/components/agents/agent.py而 HITL 能力则演化为独立的 hooks 体系见下文源码级对照小节。从零搭建一个带确认策略的 Agent文档给出了一个最小可运行的示例我们把 import、工具定义、策略配置、运行与断言拆开讲解from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack.tools.tool import Tool from haystack_experimental.components.agents import Agent from haystack_experimental.components.agents.human_in_the_loop import ( HumanInTheLoopStrategy, AlwaysAskPolicy, NeverAskPolicy, SimpleConsoleUI, ) calculator_tool Tool(namecalculator, descriptionA tool for performing mathematical calculations., ...) search_tool Tool(namesearch, descriptionA tool for searching the web., ...) agent Agent( chat_generatorOpenAIChatGenerator(), tools[calculator_tool, search_tool], confirmation_strategies{ calculator_tool.name: HumanInTheLoopStrategy( confirmation_policyNeverAskPolicy(), confirmation_uiSimpleConsoleUI() ), search_tool.name: HumanInTheLoopStrategy( confirmation_policyAlwaysAskPolicy(), confirmation_uiSimpleConsoleUI() ), }, ) # Run the agent result agent.run( messages[ChatMessage.from_user(Find information about Haystack)] ) assert messages in result # Contains conversation history这段代码展示了三个关键点工具与生成器解耦OpenAIChatGenerator负责对话与工具调用决策Tool只声明名称、描述和调用签名按工具配置确认策略confirmation_strategies是一个以工具名为键的字典。这里calculator走NeverAskPolicy静默执行而search走AlwaysAskPolicy每次都询问体现低风险工具放行、高风险工具把关的典型治理模式运行结果以对话为主run返回的字典必然包含messages键完整对话历史也包含last_message以及state_schema中声明的额外键。注意示例中的Tool(...)参数用...占位真实场景下要么传入带Annotated类型标注的函数配合tool装饰器要么通过Tool直接描述可调用对象。当前主仓库中工具的统一抽象见 haystack/tools/tool.py而ToolsType既接受单个Tool列表也接受Toolset见 Agent 的工具归一化逻辑。构造参数逐项精讲Agent.__init__采用**关键字专用参数keyword-only**签名完整参数如下参数类型默认值作用chat_generatorChatGenerator必填驱动 Agent 的聊天生成器必须支持 tools 参数toolsToolsType \| NoneNone可用工具列表或一个Toolsetsystem_promptstr \| NoneNoneAgent 的系统提示词exit_conditionslist[str] \| None[text]退出条件列表state_schemadict[str, Any] \| NoneNone工具共享的运行时状态 schemamax_agent_stepsint100最大执行步数上限streaming_callbackStreamingCallbackT \| NoneNone流式回调可同时用于输出工具结果raise_on_tool_invocation_failureboolFalse工具调用失败时是否抛异常confirmation_strategiesdict[str, ConfirmationStrategy] \| NoneNone按工具名配置的 HITL 确认策略tool_invoker_kwargsdict[str, Any] \| NoneNone透传给底层 ToolInvoker 的额外参数chat_message_storeChatMessageStore \| NoneNone聊天历史存取存储memory_storeMemoryStore \| NoneNone记忆存取存储各参数要点chat_generator构造时会对生成器的run方法做签名内省检查是否包含tools参数不满足则抛TypeError。当前主库中的等价校验见 agent.py 的构造校验逻辑tools in inspect.signature(chat_generator.run).parameters。exit_conditions可包含text模型生成无工具调用的消息即返回或工具名该工具执行完成后即返回。默认[text]。传入非法值会抛ValueError。当前主库对应实现位于 agent.py 的退出判定 与 _check_exit_conditions后者还会剔除执行出错的退出工具避免带错误退出。state_schema定义 Agent 运行时状态的类型结构工具可通过inputs_from_state/outputs_to_state读写状态键。当前主库用State类承载该机制haystack/components/agents/state/state.py且保留了一批不可覆盖的元数据键step_count、token_usage、tool_call_counts、exit_reason见 agent.py L77-L82。max_agent_steps默认100。超出后 Agent 停止并返回当前状态。主库循环到达上限时会记录警告日志并将exit_reason置为max_agent_steps见 agent.py L889-L899。streaming_callback模型响应流式输出时被调用同一个回调也可以配置为在工具被调用时输出工具结果。raise_on_tool_invocation_failure为True时工具失败直接抛异常为False默认时把异常包装成一条聊天消息交还给 LLM让模型自行纠正后重试。tool_invoker_kwargs把额外关键字参数透传给内部 ToolInvoker例如控制并发或超时行为。chat_message_store/memory_store分别让 Agent 具备跨轮次的对话历史持久化与记忆检索能力配合run中的chat_message_store_kwargs/memory_store_kwargs使用。run 与 run_async一次完整的多步执行run处理消息并执行工具直到满足退出条件run_async是它的异步版本逻辑相同但在可能的地方使用异步操作例如优先调用 ChatGenerator 的run_async。两者签名几乎一致def run( messages: list[ChatMessage], streaming_callback: StreamingCallbackT | None None, *, generation_kwargs: dict[str, Any] | None None, break_point: AgentBreakpoint | None None, snapshot: AgentSnapshot | None None, system_prompt: str | None None, tools: ToolsType | list[str] | None None, confirmation_strategy_context: dict[str, Any] | None None, chat_message_store_kwargs: dict[str, Any] | None None, memory_store_kwargs: dict[str, Any] | None None, **kwargs: Any, ) - dict[str, Any]各参数作用参数说明messages本次运行处理的ChatMessage列表streaming_callback运行时流式回调覆盖构造时的默认回调generation_kwargs传给 LLM 的额外生成参数逐键覆盖初始化时传入的同名参数break_point断点对象Breakpoint针对chat_generator或ToolBreakpoint针对tool_invokersnapshot之前保存的 Agent 执行快照字典可从上次中断处恢复执行system_prompt覆盖默认系统提示词tools本次运行的工具Tool列表、Toolset或工具名字符串列表传名字时从 Agent 已配置的工具中选取confirmation_strategy_context请求级资源字典供确认策略使用chat_message_store_kwargs传给ChatMessageStore的关键字参数如chat_history_id、last_kmemory_store_kwargs传给MemoryStore的关键字参数详见下表kwargs其余数据写入state_schema定义的状态键键必须与 schema 匹配memory_store_kwargs支持以下子项user_id按用户 ID 检索与新增记忆run_id按运行 ID 检索与新增记忆agent_id按 Agent ID 检索与新增记忆search_criteria传给search_memories方法的字典可包含filters记忆检索过滤器字典query检索查询一旦传入传入 Agent 的用户查询将不再用于记忆检索top_k返回的记忆条数include_memory_metadata是否在ChatMessage中包含记忆元数据。返回值是一个字典固定包含messages运行期间交换的全部消息last_message最后一条交换的消息以及state_schema中声明的所有额外键。可能抛出的异常RuntimeError调用run/run_async前组件未执行warm_upBreakpointException触发 Agent 断点时抛出。主库中同步与异步两条执行路径分别由 Agent.run 与 Agent.run_async 实现二者共用_initialize_fresh_execution初始化状态循环体内每个 step 的LLM 调用 → 工具执行 → 退出检查流程见 _run_step。退出条件Agent 何时停下退出条件是控制 Agent 行为边界的关键。文档规定的语义如下文本退出exit_conditions含text时模型产出一条不含工具调用的回复即退出默认行为工具退出把某个工具名加入exit_conditions则该工具成功执行一次后立即退出last_message将是该工具的结果消息步数兜底无论哪种退出条件max_agent_steps默认 100始终是硬上限超出即停止并返回当前状态。主库进一步细化了退出原因的语义——run返回值中的exit_reason可以是text、length或content_filter模型返回了不完整回复、满足退出条件的工具名、max_agent_steps或 hook 通过内部stop_run状态键提供的自定义原因参见 agent.py 的退出原因常量 与 返回值文档。exit_reason很适合配合ConditionalRouter做下游路由分流。Human-in-the-Loop确认策略体系HITL 是本文档实验 API 的核心增量。它通过confirmation_strategies把是否执行某个工具的决定权交给策略对象形成按工具维度可编程的人工审核点。HumanInTheLoopStrategy 的两大构件每个HumanInTheLoopStrategy由两部分组装confirmation_policy确认策略回答要不要问——例如AlwaysAskPolicy无条件询问、NeverAskPolicy无条件放行confirmation_ui确认界面回答怎么问——SimpleConsoleUI用标准输入输出逐行提示适合命令行场景。当前主库把这一对概念拆成了三个抽象协议定义见 haystack/hooks/human_in_the_loop/types/protocol.pyConfirmationPolicy.should_ask(tool_name, tool_description, tool_params) - bool是否发起确认ConfirmationUI.get_user_confirmation(tool_name, tool_description, tool_params) - ConfirmationUIResult向用户展示工具与参数并收集决定ConfirmationStrategy.run(...) - ToolExecutionDecision整合前两者产出可执行的决定。ConfirmationUIResult携带三种动作之一——confirm确认执行、reject拒绝执行可附feedback理由、modify修改参数后执行通过new_tool_params携带新参数ToolExecutionDecision则是策略产出的最终决定字段包括tool_name、execute、tool_call_id、feedback与final_tool_params数据结构定义见 haystack/hooks/human_in_the_loop/dataclasses.py。确认→执行的完整链路在主库 BlockingConfirmationStrategy 中可以看到一条清晰的决策链路先问策略confirmation_policy.should_ask(...)返回False则直接构造执行决策返回需要确认时调用confirmation_ui.get_user_confirmation(...)阻塞等待用户输入把 UI 结果回传给confirmation_policy.update_after_confirmation(...)策略可借此记住已确认过的调用见下文AskOncePolicy按结果分支reject→ 返回executeFalse并附反馈模板文本modify→ 用new_tool_params替换参数并返回executeTrueconfirm→ 原样执行。拒绝与修改都会产生反馈消息并写回对话历史让 LLM 知道发生了什么。主库内置的三条反馈模板strategies.py L24-L28Tool execution for {tool_name} was rejected by the user. The parameters for tool {tool_name} were updated by the user to: {final_tool_params} With user feedback: {feedback}确认策略家族主库 haystack/hooks/human_in_the_loop/policies.py 提供了三种开箱即用的ConfirmationPolicy策略should_ask行为AlwaysAskPolicy恒返回True每次工具调用都请求确认NeverAskPolicy恒返回False永远放行AskOncePolicy对同一工具 相同参数只询问一次确认过之后不再重复打扰AskOncePolicy内部维护_asked_tools: dict[str, Any]在update_after_confirmation中记录已确认的 (工具名 → 参数) 对should_ask时先查表。这类记住用户决定的策略非常适合批量处理场景避免对重复调用反复打断用户。确认界面命令行交互细节主库在 haystack/hooks/human_in_the_loop/user_interfaces.py 提供了两个ConfirmationUISimpleConsoleUI纯标准输入输出。提示Confirm execution? (yconfirm / nreject / mmodify)接受y/yes、n/no、m/modify三组输入拒绝时额外询问可选的反馈文本修改模式下逐参数提示新值——字符串参数按原样输入非字符串参数按 JSON 解析非法 JSON 会提示重试。无参数工具选择修改时直接跳过。RichConsoleUI基于rich库需pip install rich用 Panel 展示工具名、描述与参数提供y / n / m三个选项交互同样带输入校验与 JSON 解析。两个 UI 都用一把全局锁_ui_lock串行化交互避免并发运行时终端输入互相干扰。异步与 Web 场景confirmation_strategy_context阻塞式命令行确认只适合本地脚本。在 Web/服务端场景中你无法让 Agent 所在进程阻塞等待终端输入——此时应使用run/run_async的confirmation_strategy_context参数它是**请求级request-scoped**的资源字典可放入 WebSocket 连接、异步队列、Redis pub/sub 客户端等对象让确认策略以非阻塞方式与用户交互。每次请求传入各自的上下文对象天然支持多用户并发。主库中这一机制演化为 Agent 的hook_context参数由ConfirmationHook通过state.data.get(hook_context)读取见 hooks.py 的说明。断点式确认BreakpointConfirmationStrategyBlockingConfirmationStrategy要求现在就能问到人但许多真实场景下当下无法即时交互例如后台任务、无人值守流水线、需要异步审批的工作流。实验 API 为此提供了断点式breakpoint确认BreakpointConfirmationStrategy(snapshot_file_path...)构造时指定快照保存目录。每次需要确认时它的run不返回任何决策而是无条件抛出HITLBreakpointExceptionHITLBreakpointException携带四段信息——message异常消息、tool_name被暂停的工具名、snapshot_file_path已保存的 pipeline 快照文件路径、tool_call_id可选用于关联具体某次工具调用便于追踪与回溯审批决定Agent 捕获该异常后会把当前完整执行状态包括工具调用细节序列化到快照从而暂停整个执行。这份快照稍后可以被外部系统展示给用户审核恢复路径上可使用工具函数get_tool_calls_and_descriptions_from_snapshot(agent_snapshot, breakpoint_tool_onlyTrue)从AgentSnapshot中提取工具调用与工具描述默认只处理触发断点的那一个工具调用并重建其参数方便把这次要执行的工具及其参数原样呈现给用户做确认传breakpoint_tool_onlyFalse则返回全部工具调用。返回值为二元组工具调用字典列表 工具描述字典。这一机制与run的break_point、snapshot参数配合断点暂停 → 人工审批 → 携带新snapshot恢复执行构成完整的人工审批闭环。序列化与反序列化实验 API 中的 Agent 与确认策略都实现了标准 Haystack 序列化协议可无缝嵌入 YAML/JSON 定义的 pipelineAgent.to_dict() - dict[str, Any]把组件序列化为字典Agent.from_dict(data)类方法从字典还原组件。二者覆盖chat_generator、tools、confirmation_strategies等全部构造参数的往返。BreakpointConfirmationStrategy.to_dict() / from_dict()同样支持完整往返保证包含断点策略的 Agent 可以被安全地持久化、传输与恢复。主库中对应实现可见 agent.py 的 to_dict/from_dict以及 strategies.py 的序列化辅助——后者把元组工具名键编码为 JSON 数组字符串以绕过字典键必须是字符串的限制。源码级对照从实验版到主库的演进本文档记录的是haystack_experimental扩展包中的实验 API。在当前主仓库中这套能力已经演进并整合进核心代码库但接口形态发生了变化对照如下1. 确认策略的挂载方式构造参数 → hook。实验版通过Agent(confirmation_strategies{...})构造参数挂载主库改用ConfirmationHook挂在 Agent 的before_toolhook 点上haystack/hooks/human_in_the_loop/hooks.py通过hooks{before_tool: [hook]}传入 Agent。该 hook 声明了allowed_hook_points (before_tool,)若注册到其他 hook 点会被 Agent 校验拒绝。主库的confirmation_strategies还支持通配符键*对未单独配置的工具生效更具体的键优先以及元组键多个工具共享同一策略见 _get_confirmation_strategy。2. 请求级资源confirmation_strategy_context→hook_context。主库Agent.run(..., hook_context{...})把每请求资源写入状态ConfirmationHook通过state.data.get(hook_context)读取后转发给策略语义与实验版的confirmation_strategy_context一致见 agent.py hook_context 说明。3. Agent 循环的可观测性增强。主库run返回值在messages/last_message之外增加了step_count、token_usage、tool_call_counts、exit_reason等元数据键agent.py L853-L869并通过on_exithook 的continue_run控制标志支持阻止退出、继续循环agent.py L1163-L1175。4. 测试佐证。主库为整套 HITL 机制提供了针对性测试test/hooks/human_in_the_loop/test_strategies.py策略决策分支、test_policies.pyAlwaysAskPolicy/NeverAskPolicy/AskOncePolicy行为、test_hooks.pyConfirmationHook与 Agent 的集成可据此验证文中所述行为。5. 一处行为差异需注意实验版文档中ToolInvoker的配置通过tool_invoker_kwargs透传主库 Agent 则将相关能力拆分为tool_concurrency_limit并行工具调用上限默认 4与tool_streaming_callback_passthrough等显式参数agent.py 构造参数。小结实验版 Agents API 为 Haystack 提供了三件套provider 无关的工具调用循环Agentexit_conditionsmax_agent_steps、可编程的人工审核confirmation_strategies 策略/UI 组合、以及可中断可恢复的异步审批流BreakpointConfirmationStrategyHITLBreakpointException 快照恢复。其中AlwaysAskPolicy守护高成本/高风险操作、NeverAskPolicy放行低风险调用、AskOncePolicy避免重复打扰的用法可直接迁移到生产 Agent 的权限与审计设计中。如果你在当前主仓库中开发建议优先采用演进后的ConfirmationHook体系haystack/hooks/human_in_the_loop/它提供了更细粒度的 hook 点、通配符策略匹配与完整的序列化支持而本文档所述的实验 API 则是理解这套设计意图的最佳起点。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考