人工智能大模型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点击查看免费下载导读本文基于开源仓库中的 Python SDK 变更记录 python/v0.1.5发布于 2025-05-26包名strands-agents逐条拆解该版本的核心变更动态 System Prompt 覆盖、推理reasoning文本进入回调处理器、SlidingWindowConversationManager的重大升级、事件循环重构、Agent.stream_async()的 OpenTelemetry Span 生命周期修复以及 OpenAI 模型请求格式化的兼容性修复。读完本文你将掌握如何在生产代码中按调用覆盖系统提示词、消费流式推理文本、精细调优滑窗上下文管理策略并理解这些能力背后的源码实现与测试验证路径。一、版本概览v0.1.5 的定位与变更全景python/v0.1.5是strands-agentsPython SDK 在 2025-05-26 发布的一个功能与稳定性并重的版本。根据 pyproject.toml 的配置包名为strands-agents版本号由 git tag 动态生成dynamic [version]且 hatch 的tag_regex ^python/v(?Pversion.)$与变更日志中的tag: python/v0.1.5一一对应——即该版本对应仓库中的python/v0.1.5标签。本版本共包含 12 条变更记录按类型归纳如下类型数量涉及范围feat新功能3handlers推理文本回调、动态 System Prompt 覆盖、SlidingWindowConversationManager 更新fix修复3OpenAI 模型 tool arguments、README logo 配色、stream_async()agent span 生命周期docs文档4README 徽章、logo、标题规范化、仓库链接other其他2事件循环重构、版本发布其中三项新功能PR 108、PR 109、PR 120分别由三位新贡献者Shubhamraut01、josephgultekin、Unshure提交是本次版本的重点。下面按功能主题深入展开。二、按调用覆盖 System Prompt动态系统提示词能力PR 1082.1 使用方式从构造时固定到调用时动态Agent在构造时通过system_prompt参数设定模型行为基线这属于常规用法。v0.1.5 引入的动态 System Prompt 覆盖功能PR 108允许在每次调用agent(...)/agent.stream_async(...)时临时传入system_prompt覆盖 Agent 实例的默认提示词从而实现同一 Agent 实例在不同任务间切换角色或指令。以测试 test_agent.py 中的验证逻辑为参照一次典型的动态覆盖调用形如agent( test message, system_promptOverride system prompt, # 本次调用临时覆盖默认 system_prompt some_valuea_value, )测试断言的关键点在于system_prompt会进入本次调用的invocation_state事件循环在发起模型请求时读取的是覆盖后的值invocation_state[system_prompt] override_system_prompt而非 Agent 构造时的默认值。这意味着动态覆盖是按调用生效、不污染实例状态的——下一次不传system_prompt时仍回落到默认提示词。2.2 源码实现setter 与 invocation_state 的配合从源码结构看Agent类对系统提示词的管理位于 agent.pysystem_prompt是只读属性返回split_system_prompt(self._system_prompt_content)[0]保证与既有期望字符串接口的代码兼容system_promptsetter 接受str | list[SystemContentBlock] | None内部统一转换为_system_prompt_content内容块列表字符串会被包装为[{text: ...}]system_prompt_content属性则返回内容块列表本身供需要多模态系统块的模型适配层直接消费。配套测试覆盖了三种 setter 场景字符串赋值、内容块列表赋值、置None清空见 test_agent.py。动态覆盖正是复用这套 setter 语义在调用路径上把kwargs/invocation_state中的system_prompt透传到事件循环最终由_start_agent_trace_spanagent.py连同system_prompt_content一起写入追踪 Span 属性保证覆盖后的提示词在可观测链路中可追溯。2.3 典型应用场景动态覆盖最直接的落地场景包括多租户/多角色同一个 Agent 实例服务不同业务域按请求切换专家角色提示词A/B 提示词实验同一任务批量对比不同 System Prompt 的回复质量无需重建实例会话级定制结合invocation_state透传的其他上下文如用户画像、地区配置在运行时拼装个性化指令。三、推理文本进入回调处理器Reasoning 的可观测与终端呈现PR 1093.1 变更内容PR 109add reasoning text to callback handler and related tests让模型输出的推理内容reasoning text与签名signature能够流入回调事件。此前推理内容只在模型流式层内部流转外部回调处理器无法感知v0.1.5 之后回调事件中新增了reasoning、reasoningText、reasoning_signature字段。3.2 源码与测试双重佐证在 callback_handler.py 中PrintingCallbackHandler.__call__显式读取reasoningText并在终端原样打印reasoningText kwargs.get(reasoningText, False) data kwargs.get(data, ) complete kwargs.get(complete, False) ... if reasoningText: print(reasoningText, end)配套测试 test_agent.py 精确验证了回调事件携带的字段组合unittest.mock.call( agentagent, delta{reasoningContent: {text: value}}, ... reasoningTrue, reasoningTextvalue, request_state{}, ) unittest.mock.call( agentagent, delta{reasoningContent: {signature: value}}, ... reasoningTrue, reasoning_signaturevalue, request_state{}, )同时最终AgentResult.message.content中的推理块以{reasoningContent: {reasoningText: {text: ..., signature: ...}}}形式完整保留test_agent.py说明推理内容不仅在流式过程中可被回调消费还会随结果消息持久化。3.3 实战价值对于部署了带推理能力模型如 Anthropic 系 reasoning 模型的 Agent 应用此变更意味着终端交互PrintingCallbackHandler可在输出最终答案前先行呈现思考过程提升可解释性自定义回调自研CompositeCallbackHandler同文件 callback_handler.py可将reasoningText分流到日志、审计或分析管道实现推理链的合规留存。四、SlidingWindowConversationManager 升级滑窗、主动压缩与按轮管理PR 120PR 120 对滑动窗口会话管理器做了系统性增强是 v0.1.5 中与长对话场景最相关的改动。实现位于 sliding_window_conversation_manager.py。4.1 构造参数全解SlidingWindowConversationManager( window_size: int 40, should_truncate_results: bool True, *, per_turn: bool | int False, pin_first: int | None None, proactive_compression: bool | ProactiveCompressionConfig | None None, )参数类型/默认值含义与取值说明window_sizeint默认40历史消息窗口上限。超过该值才触发缩减设为0表示每次缩减时清除全部非固定消息。负数会抛ValueErrorshould_truncate_resultsbool默认True是否对超大工具结果做部分截断仅响应式溢出恢复路径生效per_turnbool \| int默认False在 Agent 循环内部主动执行消息管理的时机False仅在循环结束finally 块管理True每次模型调用前管理N正整数每 N 次模型调用管理一次pin_firstint \| None默认None固定对话开头 N 条消息缩减时受保护不被驱逐proactive_compressionbool \| ProactiveCompressionConfig \| None默认None模型调用前的主动压缩True在上下文窗口使用率达 70% 时压缩{compression_threshold: float}自定义阈值0, 1]False/None关闭仅保留响应式溢出恢复4.2 工具结果的智能截断当上下文溢出响应式路径e非空时管理器优先从最旧的、含工具结果的消息开始截断_find_oldest_message_with_tool_results以最大化保留近期相关上下文。截断策略_truncate_tool_results细节文本块保留首尾各 200 字符_PRESERVE_CHARS 200中间替换为... [truncated: N chars removed] ...说明性占位工具结果中嵌套的图片块被替换为文本占位符格式如[image: media_type, bytes bytes]避免图片持续占据上下文预算已截断过的文本带... [truncated:标记不会二次截断。4.3 合法的裁剪边界trim point 逻辑缩减不是简单砍掉最旧 N 条而是通过find_valid_trim_point寻找合法边界保证裁剪后消息序列对模型提供商仍合法sliding_window_conversation_manager.py边界必须以user 消息开头大多数模型提供商的要求不能以孤立的toolResult开头不能以toolUse开头除非其toolResult紧随其后。值得注意的 Python 特有增强_find_tool_pair_trim_point提供了兜底路径——当找不到纯 user 消息边界时回退到assistant(toolUse) user(toolResult)完整配对边界因为提供商将完整 toolUse/toolResult 配对视为合法的对话延续。这使得工具密集型对话如浏览器自动化、多轮检索也能被正常裁剪而不会被无合法边界卡死。当确实无法缩减时响应式路径抛ContextWindowOverflowException主动/例行路径仅记录 warning 并返回。4.4 per_turn循环内的主动上下文管理per_turn是本次升级针对长循环 Agent场景的关键能力。其钩子注册在register_hookssliding_window_conversation_manager.py通过监听BeforeModelCallEvent实现回调内部_on_before_model_call维护_model_call_count并按配置决定是否立即执行apply_management。测试 test_conversation_manager.py 系统验证了该行为per_turnFalse6 次模型调用期间不触发管理仅在 finally 块执行一次per_turnTrue每次模型调用前都管理per_turn2第 2、4、6 次模型调用前各管理一次另加循环结束一次per_turn0或负数抛ValueError。官方建议源码 docstring若 Agent 在循环中执行大量工具操作如带频繁截图的网页浏览应启用per_turnTrue主动管理历史防止循环变慢若性能仍有压力可调整为per_turn5之类的频率。4.5 会话状态持久化管理器状态支持跨会话恢复get_state()将model_call_count纳入状态字典sliding_window_conversation_manager.pyrestore_from_session()在恢复时还原计数同文件 L137-L148保证per_turn的调度节奏在会话续接后不中断。五、事件循环重构PR 106与 stream_async 的 Span 修复PR 1195.1 Rise of the Phoenix事件循环重构PR 106️ Rise of the Phoenix: Event Loop Refactor对 SDK 的核心执行引擎做了重构。当前事件循环实现位于 event_loop.py职责被清晰划分为多个函数event_loop_cycle/recurse_event_loop单轮循环与递归式循环入口_handle_model_execution模型调用及流式事件处理_handle_tool_execution工具调用与结果回填_stop_for_interrupts中断interrupt收集与终止决策_check_limits按轮次/输出 token/总 token 的预算检查。从模块结构看重构后的事件循环将模型执行、工具执行、中断处理解耦为独立阶段并通过BeforeModelCallEvent/AfterModelCallEvent/BeforeToolsEvent/AfterToolsEvent等钩子对外暴露插桩点为上文提到的per_turn主动管理、动态 System Prompt 覆盖等能力提供了统一的执行期介入机制。5.2 agent span 生命周期修复PR 119 修复了Agent.stream_async()场景下 agent span 的起止问题。在 agent.py 的stream_async实现中可以看到修复后的生命周期编排输入消息转换完成后立即self.trace_span self._start_agent_trace_span(messages)L1386并在with trace_api.use_span(self.trace_span)作用域内驱动整个事件循环正常结束时self._end_agent_trace_span(responseresult)L1419异常路径self._end_agent_trace_span(errore)L1424取消路径通过end_span_with_cancellation结束agent.py。_start_agent_trace_spanagent.py会携带agent_name、model_id、tools、system_prompt、system_prompt_content、trace_attributes与完整工具配置形成包含系统提示词与工具清单的 agent 根 Span底层实现在 tracer.pystart_agent_span/end_agent_span。修复后流式调用全程含流式结束后的AgentResultEvent回调都落在正确的 agent span 内OTLP/console 导出的追踪数据不再出现有结果无 span或span 提前闭合的错位。5.3 对可观测性的影响这一组合事件循环重构 span 修复意味着使用Agent.stream_async()构建流式应用的团队可以在 Jaeger、Grafana 等 OTel 后端获得完整的 agent → 模型调用 → 工具调用 span 树并配合MetricsClient的 usage/metrics 统计定位长会话中的上下文膨胀点。六、OpenAI 模型适配修复tool arguments 边界处理PR 97PR 97models - openai - argument none属于模型适配层的兼容性修复。从当前源码 openai.py 看OpenAI 请求格式化通过format_request_message_tool_call将toolUse的输入序列化为工具调用参数arguments: json.dumps(tool_use[input], ensure_asciiFalse),该修复针对的正是arguments可能为空的边界场景——变更日志记录为argument none。可以推断修复确保了当模型返回的 tool use 缺少 input 时请求序列化不会产生非法结构例如空字符串或None被错误序列化从而维持 OpenAI API 兼容性。配套消息组装逻辑在 openai.py仅当存在toolUse内容块时才生成tool_calls字段且图片块会被从工具消息中拆分为独立 user 消息_split_tool_message_imagesL446-L455满足 OpenAI 对图片必须位于 user 角色的约束。七、元数据与文档更新PR 100–105v0.1.5 还包含一组 README 层面的变更PR 100/101/102/104/105新增 open PRs 徽章、链接到 samples 示例仓库、将 Docs 统一为 Documentation、加入 logo并将 logo 改为跟随用户配色偏好自动切换明暗的方案先尝试暗色 logo最终采用随prefers-color-scheme自动变色的实现。这类变更虽不涉及运行时行为但对开源项目的可发现性与 README 的可读性有实际价值也反映了发布流程对仓库门面的一致化治理。八、升级与验证让 v0.1.5 落地8.1 安装pip install strands-agents0.1.5包元数据见 pyproject.tomlname strands-agents版本由 git tagpython/v0.1.5动态解析。8.2 行为验证清单升级后建议重点回归以下路径仓库自带测试可直接运行验证动态 System Prompttests/strands/agent/test_agent.py中test_agent__call__with_invocation_state类用例断言覆盖值进入invocation_state[system_prompt]推理回调同文件 L812-L833 的回调事件断言验证reasoningText/reasoning_signature字段滑窗管理tests/strands/agent/test_conversation_manager.py中test_per_turn_*系列与test_sliding_window_proactive_compression_skips_tool_result_truncation覆盖参数校验、钩子注册、按轮调度与主动压缩路径。8.3 升级注意点per_turn参数有严格的取值约束0与负整数抛ValueError迁移旧配置时需确认取值合法若依赖回调事件结构需注意新增的reasoning相关字段是增量字段不破坏既有data/complete/tool_use语义事件循环重构后若曾自定义中间件或深度依赖内部事件顺序建议以 event_loop.py 的公开阶段函数为准重新对齐。结语v0.1.5 是一次功能增量 引擎加固并行的版本动态 System Prompt 覆盖与推理回调让 Agent 的输入与输出都更加可编程滑动窗口管理器的per_turn、pin_first、proactive_compression三件套为长会话场景提供了可调优的上下文治理方案事件循环重构与 span 修复则夯实了流式场景下的可观测性底座。对正在用strands-agents构建生产级 Agent 的团队而言本文涉及的每个能力点都能在仓库源码agent.py、sliding_window_conversation_manager.py、callback_handler.py、event_loop.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会话管理如何通过滑动窗口与摘要技术优化AI对话终极指南Strands Agents会话管理如何通过滑动窗口与摘要技术优化AI对话 Strands Agents是GitHub加速计划下的sdk python人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务如何用Akagi在30天内从麻将新手晋升为战略高手终极AI辅助指南 ️如何用Akagi在30天内从麻将新手晋升为战略高手终极AI辅助指南 ️ 你是否曾在雀魂对局中感到迷茫看着手中的牌无从下手或者明明感觉能胡牌却总是差那人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务windows-rs 中的 Windows Window轻量级 Win32 窗口创建与消息循环实战指南windows rs 中的 Windows Window轻量级 Win32 窗口创建与消息循环实战指南 导读 windows window 是 windows人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考