人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载本篇文章基于 strands-agents Python SDK 的 v1.13.0 版本变更记录site/src/content/changelog/sdk/python-v1.13.0.md展开聚焦该版本在 Agent 调用 API、OpenTelemetry 可观测性语义、工具装饰器校验与中断Interrupt机制上的核心改动。读完本文你将掌握invocation_state的用法与迁移要点、timeToFirstByteMs等新指标在 span/metrics 中的落点、ToolContext参数命名约束以及工具调用前中断这一人机协作模式的实现原理并能直接对照仓库源码理解每条变更的底层逻辑。一、版本概览一次以调用状态收敛 可观测性升级为主的迭代v1.13.0发布于 2025-10-17共包含 9 条变更全部为非破坏性breaking: false覆盖agent、telemetry/otel、tool/decorator、structured-output、multiagents五个关注域可归为四条主线主线涉及条目影响面Agent 调用 API 收敛用invocation_state取代散落的kwargsPR 966所有调用入口可观测性语义升级语义约定更新、新增timeToFirstByteMsPR 997、新增gen_ai.tool.description/gen_ai.tool.json_schemaPR 1027OTel span 与指标工具层可靠性ToolContext参数名校验PR 1028、Python 3.10 异常注解PR 1034、装饰工具的中断支持PR 1041工具开发与执行生命周期/集成修复工具调用前钩子支持中断PR 987、多智能体中断时抛异常PR 1038、结构化输出集成测试去 flakyPR 1030钩子与多智能体编排其中other类型的条目PR 987/1030/1038/1041虽然不计入新功能但它们在钩子中断、多智能体异常语义上同样承载了实质行为变更本文一并覆盖。二、核心变更Agent 调用 API 全面引入 invocation_state2.1 变更内容与动机PR 966作者 JackYPCOnline将 Agent 调用 API 中依赖**kwargs透传的机制正式替换为显式的invocation_state参数。在旧实现中调用方需要依赖额外关键字参数会被直接透传给事件循环这一隐式约定新实现把这类透传数据收敛为一个类型明确、可文档化、可校验的dict[str, Any]从而让事件循环、中间件、工具执行器都能以统一的方式读取调用级上下文。2.2 源码中的实际签名以同步入口Agent.__call__为例在 strands-py/src/strands/agent/agent.py 中def __call__( self, prompt: AgentInput None, *, invocation_state: dict[str, Any] | None None, structured_output_model: type[BaseModel] | None None, structured_output_prompt: str | None None, idempotency_token: Any None, limits: Limits | None None, cancel_signal: threading.Event | None None, **kwargs: Any, ) - AgentResult:invoke_async与stream_async采用了完全一致的签名见 agent.py且invoke_async内部通过self.stream_async(prompt, invocation_stateinvocation_state, ...)将其显式传递给流式事件循环。docstring 中明确标注**kwargs仍被保留但已标记为[Deprecating]——这意味着旧代码短期内依然可运行但新代码应优先使用invocation_state。2.3 invocation_state 的实际消费方从仓库源码结构看invocation_state并非仅停留在签名层面而是贯穿事件循环与工具执行链事件循环event_loop/event_loop.py 与 event_loop/streaming.py 将其作为透传上下文工具执行tools/_caller.py、tools/executors/sequential.py 与 tools/executors/concurrent.py 会把它带入工具调用钩子事件BeforeToolCallEvent/AfterToolCallEvent中直接暴露invocation_state字段见下文第五节的 hooks/events.py模型层models/model.py 与多智能体的 multiagent/base.py、multiagent/graph.py、multiagent/swarm.py 同样读取该字段中间件_middleware/stages.py 将其纳入中间件阶段的上下文。2.4 迁移建议对于 v1.13.0 的使用者from strands.agent import Agent # 新写法显式传递调用状态 agent Agent(modelmodel) result agent(查询一下库存, invocation_state{request_id: req-42, tenant: demo}) # 旧写法仍可用但已标记 Deprecating # result agent(查询一下库存, request_idreq-42)在工具函数中通过ToolContext读取该状态即可实现调用级元数据如请求 ID、租户、用户身份随一次调用流转到工具内部的透传无需再依赖全局变量或线程局部存储。三、可观测性升级语义约定更新与 timeToFirstByteMs 落地3.1 变更内容PR 997作者 poshinchen更新了 GenAI 语义约定semantic conventions并新增timeToFirstByteMs指标同时写入 span 属性与 OTel 指标PR 1027 则进一步补充了gen_ai.tool.description与gen_ai.tool.json_schema两个工具级语义属性。3.2 timeToFirstByteMs 在 span 中的落点在 strands-py/src/strands/telemetry/tracer.py 的_add_optional_usage_and_metrics_attributes中模型调用的耗时指标被映射为 GenAI 语义属性if metrics.get(timeToFirstByteMs, 0) 0: attributes[gen_ai.server.time_to_first_token] metrics[timeToFirstByteMs] if metrics.get(latencyMs, 0) 0: attributes[gen_ai.server.request.duration] metrics[latencyMs]也就是说timeToFirstByteMs首字节/首 token 到达耗时对应语义属性gen_ai.server.time_to_first_token而整体延迟latencyMs对应gen_ai.server.request.duration。这一定义在 types/event_loop.py 与 event_loop/streaming.py 中由事件循环产出并被 telemetry/metrics.py 同步记录为指标if metrics.get(timeToFirstByteMs) is not None: self._metrics_client.model_time_to_first_token.record(metrics[timeToFirstByteMs])对应的单测位于 strands-py/tests/strands/telemetry/test_tracer.py 与 strands-py/tests/strands/telemetry/test_metrics.py可用于验证属性名与指标名的实际映射。3.3 语义约定稳定性开关与工具属性v1.13.0 之前的版本已支持通过环境变量OTEL_SEMCONV_STABILITY_OPT_IN选择语义约定稳定性级别tracer.pygen_ai_latest_experimental启用最新的 GenAI 语义约定gen_ai_tool_definitions在 span 中记录gen_ai.tool.definitions工具定义集合gen_ai_use_latest_invocation_tokens使用最新的 invocation token 命名gen_ai_span_attributes_only把消息内容直接记录为 span 属性而非 span 事件适用于无法读取 span 事件的后端如 Langfusegen_ai_unredacted_attributeslist按;分隔、支持尾部*通配的敏感属性白名单未命中白名单的gen_ai.input.messages、gen_ai.output.messages、gen_ai.system_instructions、gen_ai.tool.call.arguments、gen_ai.tool.call.result等敏感属性会被脱敏默认不启用脱敏向后兼容。PR 1027 补充的gen_ai.tool.description与gen_ai.tool.json_schema属于工具定义维度。结合 tracer.py 中已有的工具 span 实现gen_ai.tool.name、gen_ai.tool.call.id、按最新约定记录的gen_ai.tool.call.arguments/gen_ai.tool.call.result以及gen_ai.tool.status工具的描述与 JSON Schema 属性让可观测后端能更完整地重建模型看到了哪些工具、工具长什么样对调试工具选择与参数生成错误尤其有价值。配置建议若你的后端如 Langfuse 或自建 OTLP Collector已支持最新 GenAI 语义约定可设置OTEL_SEMCONV_STABILITY_OPT_INgen_ai_latest_experimental,gen_ai_tool_definitions以获得工具定义、TTFT、工具调用参数等更丰富的信息若对敏感内容有合规要求再追加gen_ai_unredacted_attributes空值表示全部敏感属性脱敏并显式放行需要的属性。四、工具装饰器加固ToolContext 参数名强校验4.1 变更内容PR 1028作者 Ratish1为tool装饰器增加了签名校验当函数参数标注了ToolContext类型时若未通过tool(context...)声明上下文参数名或参数名与声明不一致会在装饰阶段直接抛出带有明确信息的ValueError避免运行时才暴露上下文未被注入的隐性错误。4.2 源码实现校验逻辑位于 strands-py/src/strands/tools/decorator.pydef _validate_signature(self) - None: Verify that ToolContext is used correctly in the function signature. for param in self.signature.parameters.values(): annotation self.type_hints.get(param.name) if annotation is ToolContext or get_origin(annotation) is ToolContext: if self._context_param is None: raise ValueError(tool(context) must be set if passing in ToolContext param) if param.name ! self._context_param: raise ValueError( fparam_name{param.name} | ToolContext param must be named {self._context_param} ) break同时decorator.py 中ToolContext参数名本身也不允许为空ValueError(Context parameter name cannot be empty)。4.3 正确用法示例from strands.tools import tool from strands.types.tools import ToolContext tool(contexttool_context) # 必须显式声明上下文参数名 def my_tool(name: str, count: int 1, tool_context: ToolContext) - str: # tool_context.invocation_state / tool_context.agent 等可直接使用 return f{name} x {count}常见错误与报错对照错误写法报错信息参数名为ctx但声明为tool(contexttool_context)param_namectx \| ToolContext param must be named tool_context有ToolContext参数但未传contexttool(context) must be set if passing in ToolContext paramtool(context)Context parameter name cannot be empty这一校验让上下文参数漏配/误配从难以排查的运行时注入失败前置为装饰阶段的清晰报错显著降低了工具开发者的排障成本。五、工具调用前钩子支持中断BeforeToolCallEvent 的人机协作能力5.1 变更内容PR 987作者 pgrayy为工具调用前事件引入了中断interrupt能力钩子回调在执行BeforeToolCallEvent时可以直接抛出InterruptException从而在工具真正执行前暂停整个 Agent 事件循环等待外部通常是人类介入。5.2 事件定义与中断语义事件定义位于 strands-py/src/strands/hooks/events.pydataclass class BeforeToolCallEvent(HookEvent[_LocalAgentT], _Interruptible): selected_tool: AgentTool | None # 即将执行的工具钩子可替换 tool_use: ToolUse # 工具调用参数 invocation_state: dict[str, Any] # 调用级状态 cancel_tool: bool | str False # 置为非空字符串可取消本次工具调用钩子可以修改selected_tool/tool_use以替换将要执行的工具设置cancel_tool会在不执行工具的情况下返回一个 error 状态的工具结果继承自_Interruptible意味着钩子可抛出中断Interrupt/InterruptException事件的中断 ID 为fv1:before_tool_call:{tool_use[toolUseId]}:{uuid5(...)}保证同一工具调用上可区分不同命名的中断。中断的聚合逻辑在 strands-py/src/strands/hooks/registry.pyinvoke_callbacks会捕获回调抛出的中断异常、按名字去重聚合返回给事件循环由上层实现 human-in-the-loop 流程。5.3 装饰工具的中断支持PR 1041 进一步将中断能力扩展到了tool装饰器生成的工具上装饰工具的执行链路同样支持在调用前/过程中抛出中断并让事件循环暂停与钩子事件形成互补——钩子用于调用前拦一道装饰工具则可在工具自身逻辑中触发暂停。5.4 多智能体场景的行为约定PR 1038 规定在多智能体编排中如果子智能体被中断当前实现会临时抛出异常temporarily raise exception when interrupted而不是静默吞掉中断或返回空结果。这意味着在 multiagent/graph.py 或 multiagent/swarm.py 这类编排器中父级需要感知子任务的暂停状态并决定是继续、等待还是终止这一行为约定在集成测试中得到了固化见 strands-py/tests_integ/test_multiagent_graph.py 与 strands-py/tests_integ/test_multiagent_swarm.py。六、Python 3.10 兼容异常注解Exception Notes能力补齐6.1 变更内容BaseException.add_note()是 Python 3.11 才引入的 API。PR 1034作者 zastrowm为 SDK 增加了 Python 3.10 下的等价实现当运行环境不支持add_note时将注解文本追加到异常消息中从而让 SDK 内部尤其是中断与错误传播路径在 3.10 上也能携带结构化注解信息。6.2 实现细节工具函数位于 strands-py/src/strands/_exception_notes.py# add_note was added in 3.11 - we hoist to a constant to facilitate testing supports_add_note hasattr(Exception, add_note) def add_exception_note(exception: Exception, note: str) - None: if supports_add_note: exception.add_note(note) # Python 3.11 else: # For Python 3.10, append note to the exception message if hasattr(exception, args) and exception.args: exception.args (f{exception.args[0]}\n{note},) exception.args[1:] else: exception.args (note,)实现要点supports_add_note被提升为模块级常量便于测试对应的测试位于 strands-py/tests/strands/test_exception_notes.py3.10 回退路径通过改写exception.args实现注解以\n换行追加尽量保持str(exception)的可读性由于是运行时能力探测而非版本号判断3.11 之后的所有版本都会自然走原生add_note()路径。七、质量保障结构化输出集成测试去 flakyPR 1030作者 pgrayy修复了结构化输出structured output集成测试的偶发失败。这类 flaky 通常来自模型响应不稳定或时序竞争修复方式是让测试对模型输出做更宽容的断言或引入确定性重试。相关的集成测试位于 strands-py/tests_integ/test_structured_output_agent_loop.py可结合 tools/structured_output/ 目录下的实现structured_output_tool.py与_structured_output_context.py理解结构化输出工具的整体链路。八、升级清单与兼容性说明综合 v1.13.0 全部变更从旧版本升级时的核对清单如下调用 API将依赖**kwargs透传的调用逐步迁移到invocation_state参数旧写法仍可用但已标记 Deprecating可观测性确认后端是否兼容最新 GenAI 语义属性gen_ai.server.time_to_first_token、gen_ai.server.request.duration、gen_ai.tool.description、gen_ai.tool.json_schema并按需设置OTEL_SEMCONV_STABILITY_OPT_IN工具开发为所有带ToolContext参数的tool函数补齐context声明且参数名必须一致否则装饰阶段即报错钩子与中断若在BeforeToolCallEvent中实现审批/拦截逻辑可利用cancel_tool或抛出中断实现工具执行前的暂停多智能体场景注意子智能体被中断时父级会收到异常Python 版本SDK 在 3.10 上同样能携带异常注解无需在应用层做版本分支。所有变更均为非破坏性breaking: false可在不修改既有业务代码的前提下平滑升级对应的版本记录与仓库根目录下各子项目的源码、测试可直接对照查阅如 strands-py/src/strands/agent/agent.py、strands-py/src/strands/telemetry/tracer.py、strands-py/src/strands/tools/decorator.py、strands-py/src/strands/hooks/events.py。赞分享人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载相关推荐strands-agents Python SDK v0.1.4 发布解析模型层能力增强与工程化质量改进strands agents Python SDK v0.1.4 发布解析模型层能力增强与工程化质量改进 Python 版 Agent 开发框架 strand人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务kubeasz 安装 kube_master 节点全解析apiserver / scheduler / controller-manager 部署与高可用实践kubeasz 安装 kube_master 节点全解析apiserver / scheduler / controller manager 部署与高可用实践人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务Strands Agents Python SDK v1.53.0 版本深度解析Prompt 缓存、Agent 委托与 MCP 工具增强Strands Agents Python SDK v1.53.0 版本深度解析Prompt 缓存、Agent 委托与 MCP 工具增强 导读 本文围绕 St人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考