1. 为什么“手写 Agent 循环”正在变成一种负担如果你最近半年在折腾 AI Agent大概率经历过这个阶段一开始兴致勃勃地写一个while True循环把用户输入塞进 prompt调一次模型解析返回判断要不要调工具调完再把结果塞回去循环往复。第一版跑通的时候特别有成就感感觉自己掌握了 Agent 的“内核”。但很快问题就来了。工具调用格式在不同模型之间不统一有的返回 JSON有的返回 XML 标签有的干脆把参数写在自然语言里多轮对话的上下文管理越来越乱token 消耗像流水一样错误处理基本靠 try-except 硬扛模型偶尔抽风返回个空字符串整个循环就卡死了想加个流式输出、加个重试、加个可观测性代码量直接翻倍。到最后你会发现真正跟业务相关的逻辑可能只占 20%剩下 80% 都在处理 Agent 运行时的脏活累活。这就是Strands Agents Harness SDK想解决的问题。它的核心主张非常直接把 Agent 的运行时循环、工具编排、上下文管理、错误恢复这些通用能力封装成一个 SDK你只需要定义“我要什么工具”“我用哪个模型”“我的系统提示是什么”剩下的交给 Harness 去跑。标题里说的“一行代码拿到生产级 Agent”虽然有点营销色彩但它确实把 Agent 从 demo 到可用的距离压缩了很多。这篇文章我会从实际使用角度出发拆解这个 SDK 的设计思路、核心概念、上手步骤以及我在接入过程中踩过的坑。适合已经了解 Agent 基本概念、动手写过至少一个 Agent demo、但被运行时细节折磨过的开发者。如果你还在纠结“什么是 Agent”建议先补一下基础再来看这篇。2. Strands Agents Harness SDK 的整体设计与思路拆解2.1 它到底封装了什么要理解这个 SDK 的价值得先看清楚一个 Agent 运行时到底包含哪些部分。我把它拆成四层第一层是模型调用层负责跟 LLM 交互处理请求构造、响应解析、流式输出、重试和超时。第二层是工具编排层负责把工具的定义转换成模型能理解的格式解析模型的工具调用意图执行工具把结果回传。第三层是上下文管理层负责维护对话历史、裁剪超长上下文、管理 system prompt 和 few-shot 示例。第四层是循环控制层也就是那个经典的“思考-行动-观察”循环决定什么时候继续调工具、什么时候结束、什么时候触发人工介入。手写 Agent 的时候这四层全部混在一个函数里。Harness SDK 的做法是把这四层拆开每一层都有明确的抽象和默认实现同时保留扩展点。你不需要关心它内部怎么解析工具调用但如果你想换一种解析策略也能通过接口替换。这种设计的好处是关注点分离。业务开发者只需要写工具函数和系统提示运行时的事情交给 SDK。而框架开发者可以针对某一层做优化不影响其他层。2.2 为什么叫“Harness”Harness 这个词在工程领域通常指“线束”或“约束框架”在软件里常用来表示一套把零散组件组织起来、提供统一运行环境的骨架。这里用 Harness 而不是 Framework我觉得是有意为之的。Framework 通常意味着“你要按我的方式来”侵入性比较强你得继承某个基类、实现某个接口、遵循某种目录结构。而 Harness 更像是一个“外挂的运行时”你的工具函数还是普通的 Python 函数你的业务逻辑还是普通的业务逻辑Harness 只是在外面套了一层负责调度和编排。这个区别在实际使用中很关键。我试过一些 Agent 框架光是让一个已有的函数变成“工具”就要写一堆装饰器和 schema 定义。Harness 的思路是尽量利用 Python 原生的类型注解和 docstring减少样板代码。这一点后面讲工具定义的时候会具体说。2.3 方案选型背后的取舍任何 SDK 的设计都是取舍。Harness 在几个关键点上做了明确选择选择一以代码为中心而不是以配置为中心。有些 Agent 平台走的是低代码路线用 YAML 或可视化界面定义 Agent。Harness 坚持用 Python 代码定义一切。这个选择的理由是Agent 的逻辑往往需要跟现有系统深度集成纯配置的方式在复杂场景下会很快遇到天花板。用代码定义意味着你可以用 IDE 的补全、类型检查、单元测试工程化程度更高。选择二默认同步支持异步。很多新出的 Agent 框架一上来就 all-in async。Harness 的默认接口是同步的异步作为可选。这个选择对新手友好因为同步代码更容易调试。但如果你要处理高并发场景就得切到异步模式这时候要注意工具函数也得是异步的否则会阻塞事件循环。选择三工具即函数不强制 schema。这是我觉得最舒服的一点。你写一个普通的 Python 函数加上类型注解和 docstringHarness 会自动提取参数 schema 给模型。不需要手写 JSON Schema不需要维护两套定义。代价是 docstring 的质量直接影响模型调用工具的准确率所以写 docstring 的时候不能偷懒。3. 核心概念与实操要点解析3.1 Agent、Tool、Model 三个核心对象Harness SDK 的核心概念不多主要就三个Agent、Tool、Model。Agent 是编排中心它持有 Model 和一组 Tool负责驱动整个循环。你创建一个 Agent 的时候至少要传一个 Model 和一个系统提示。Tool 是可选的但实际项目里基本都会用到。Tool 在 Harness 里就是一个 Python 函数。它可以是同步的也可以是异步的。函数的名字、参数类型注解、docstring 会被自动转换成模型能理解的工具描述。这里有个细节参数类型注解必须准确因为模型会根据类型来决定传字符串还是数字。如果你把count: int写成count模型可能会传3而不是3然后在你的函数里报类型错误。Model 是模型调用的抽象。Harness 支持多种模型提供商通过统一的接口调用。切换模型的时候理论上只需要换一个 Model 实例Agent 的代码不用动。但实际使用中不同模型对工具调用的支持程度不一样有些模型在复杂工具场景下表现明显更好这个后面会讲。3.2 工具定义的三个关键细节工具定义看起来简单但有几个细节直接决定 Agent 能不能稳定工作。第一个细节是 docstring 的写法。Harness 会把 docstring 作为工具描述传给模型。模型根据这个描述来判断“什么时候该用这个工具”。所以 docstring 不能只写“查询天气”要写清楚“当用户询问某个城市的当前天气、温度、湿度时使用此工具”。描述越具体模型误用的概率越低。第二个细节是参数命名。参数名要语义化不要用a、b、x这种。模型看到city和date能理解看到arg1和arg2就只能猜。如果参数有枚举值最好在 docstring 里列出来比如“unit 参数可选 celsius 或 fahrenheit”。第三个细节是返回值。工具函数的返回值会被序列化后塞回上下文。如果返回一个巨大的字典会迅速吃掉 token。我的经验是工具返回值尽量精简只返回模型需要的信息。如果确实需要返回大量数据考虑返回一个摘要加一个引用 ID让模型按需再查。下面是一个工具定义的示例展示了上面几个细节def get_weather(city: str, unit: str celsius) - str: 查询指定城市的当前天气情况。 当用户询问某个城市的天气、温度、是否下雨等问题时使用此工具。 Args: city: 城市名称例如 北京、上海、深圳。 unit: 温度单位可选 celsius 或 fahrenheit默认为 celsius。 Returns: 包含温度、天气状况和湿度的简要描述。 # 实际实现省略 return f{city} 当前 25 度晴湿度 60%这个函数没有任何装饰器Harness 会自动识别它作为工具。参数类型注解和 docstring 就是全部的“schema”。3.3 上下文管理的默认策略与调整Harness 默认会维护完整的对话历史包括用户消息、模型回复、工具调用和工具结果。这在短对话里没问题但对话一长token 就会爆。SDK 提供了几种上下文管理策略。默认策略是“保留最近 N 轮”超过的部分会被截断。这个 N 可以配置。但简单的截断有个问题如果被截断的部分包含重要的工具调用结果模型可能会“失忆”重复调用同一个工具。更稳妥的做法是摘要式压缩当上下文超过阈值时调用一次模型把历史对话压缩成摘要保留关键信息。Harness 支持自定义压缩策略你可以实现一个压缩函数在上下文超限时被调用。我的建议是在开发阶段先用默认策略快速跑通流程。上线前一定要根据实际对话长度分布调整阈值和压缩策略。我见过一个案例客服 Agent 在对话到第 15 轮左右开始出现“重复问用户已经回答过的问题”排查下来就是上下文截断把早期信息丢了。3.4 错误处理与重试机制Agent 运行中最常见的错误有三类模型调用失败超时、限流、工具执行失败参数错误、外部服务不可用、模型返回格式异常工具调用解析失败。Harness 对这三类错误有不同的默认处理。模型调用失败默认会重试重试次数和退避策略可配置。工具执行失败默认会把错误信息作为工具结果返回给模型让模型决定下一步。模型返回格式异常默认会尝试修复修复失败则终止本轮。这里有个实操心得工具函数内部一定要自己处理可预期的异常不要把异常抛给 Harness。比如调用外部 API 的时候如果 API 返回 404你应该在工具函数里捕获返回一个“未找到”的描述而不是让异常冒泡。因为异常冒泡后Harness 会把堆栈信息塞回上下文既浪费 token又可能让模型困惑。4. 从零搭建一个可用的 Agent完整实操流程4.1 环境准备与依赖安装先确认 Python 版本。Harness SDK 要求 Python 3.9 以上我建议直接用 3.11 或 3.12类型注解的支持更完整运行速度也更好。如果你还在用 3.8先升级不然后面会遇到一些奇怪的兼容问题。安装方式很直接pip install strands-agents-harness如果你用虚拟环境强烈建议先创建再安装python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install strands-agents-harness安装完成后验证一下import strands_harness print(strands_harness.__version__)能打印出版本号就说明装好了。如果报ModuleNotFoundError检查一下是不是装到了全局环境而不是虚拟环境。4.2 配置模型接入Harness 支持多种模型提供商。配置方式通常是通过环境变量传 API Key然后在代码里指定模型名称。以常见的接入方式为例import os from strands_harness import Agent, Model os.environ[MODEL_API_KEY] your-api-key-here model Model( provideryour-provider, model_nameyour-model-name, temperature0.3, max_tokens2048 )这里有几个参数值得说明。temperature在 Agent 场景下建议设低一点0.2 到 0.4 之间比较合适因为工具调用需要稳定性太高的温度会让模型“发挥创意”选错工具或编造参数。max_tokens要根据你的工具返回长度来定如果工具返回内容较长这个值要相应调大否则模型可能还没输出完就被截断。注意API Key 不要硬编码在代码里用环境变量或密钥管理服务。我见过有人把 Key 提交到公开仓库结果被刷爆额度。4.3 定义你的第一批工具工具的定义前面讲过这里给一个更完整的例子包含两个工具一个查询订单状态一个计算退款金额。def query_order_status(order_id: str) - str: 根据订单号查询订单的当前状态。 当用户询问订单进度、是否发货、物流信息时使用此工具。 Args: order_id: 订单号通常是 12 位数字字符串。 Returns: 订单状态的文字描述包括下单时间、当前状态和预计送达时间。 # 模拟查询 mock_orders { 123456789012: 已发货预计明天送达, 987654321098: 待付款请尽快完成支付 } return mock_orders.get(order_id, 未找到该订单请确认订单号是否正确) def calculate_refund(order_id: str, reason: str) - str: 计算指定订单的退款金额。 当用户明确要求退款、询问能退多少钱时使用此工具。 Args: order_id: 订单号。 reason: 退款原因例如 质量问题、七天无理由、发错货。 Returns: 退款金额和退款政策的说明。 # 模拟计算 return f订单 {order_id} 因 {reason} 可退款 199.00 元将在 3 个工作日内原路返回注意两个工具的 docstring 都写清楚了“什么时候用”。这是模型选择工具的主要依据。如果你发现模型经常选错工具第一件事就是回去改 docstring把使用场景写得更具体。4.4 组装 Agent 并跑通第一轮对话把 Model 和 Tool 组装起来from strands_harness import Agent, Model model Model(provideryour-provider, model_nameyour-model-name) agent Agent( modelmodel, tools[query_order_status, calculate_refund], system_prompt你是一个电商客服助手。用户询问订单相关问题时先查询订单状态再回答。涉及退款时先计算退款金额再告知用户。回答要简洁友好。 ) response agent.run(我的订单 123456789012 到哪了) print(response)跑起来之后你会看到 Agent 自动调用了query_order_status然后把结果整理成自然语言回复。整个过程你只写了工具函数和系统提示循环、解析、回传都是 Harness 做的。4.5 加入流式输出与多轮对话实际产品里用户不会只问一句。多轮对话需要维护会话状态。Harness 的 Agent 实例可以复用每次run会基于之前的上下文继续response1 agent.run(我的订单 123456789012 到哪了) print(response1) response2 agent.run(那我想退款质量有问题) print(response2)第二轮对话里模型能“记得”上一轮的订单号直接调用calculate_refund不需要用户重复提供。流式输出在需要实时展示的场景很有用for chunk in agent.stream(帮我查一下订单 123456789012): print(chunk, end, flushTrue)流式模式下工具调用的过程也会以事件形式暴露出来你可以据此在前端展示“正在查询订单...”这样的状态提示。4.6 参数计算与配置调优Agent 上线前有几个参数需要根据实际场景调优。我整理了一个对照表参数默认值建议范围调整依据temperature0.70.2-0.4工具调用场景需要稳定性max_tokens10242048-4096根据工具返回长度调整max_iterations105-15防止无限循环复杂任务可调大retry_count32-5外部服务不稳定时调大context_window自动根据模型定留 20% 余量给输出max_iterations这个参数特别重要。它限制了一轮对话里模型最多调用多少次工具。设太小复杂任务跑不完设太大模型可能陷入死循环。我的经验是先设 10观察实际运行中的迭代次数分布再调整。5. 常见问题与排查技巧实录5.1 模型不调用工具直接编造答案这是最常见的问题。用户问“订单到哪了”模型不调query_order_status直接回复“您的订单正在路上”。原因是系统提示或工具描述不够强模型觉得可以直接回答。解决办法有三个层次。第一在系统提示里明确写“涉及订单状态必须调用 query_order_status 工具不得凭记忆回答”。第二在工具 docstring 里强调“必须使用此工具获取实时数据”。第三如果还是不行考虑在 Agent 配置里设置tool_choicerequired强制模型在特定场景下必须调用工具。5.2 工具参数传错类型模型把order_id传成了数字123456789012而不是字符串123456789012。如果你的函数注解是strHarness 会尝试转换但转换失败就会报错。预防方法是在 docstring 里明确参数类型比如“order_id: 订单号12 位数字字符串”。另外工具函数内部对参数做一次校验如果类型不对返回一个友好的错误描述让模型自己纠正。5.3 上下文过长导致响应变慢对话轮次多了之后每次请求都要带上完整历史token 消耗大响应也慢。除了前面说的压缩策略还有一个技巧把不必要的信息从工具返回值里去掉。比如查询订单返回了 20 个字段但模型只需要状态和预计送达时间那就只返回这两个。工具返回值精简上下文增长速度会明显下降。5.4 工具执行超时外部 API 响应慢工具函数卡住整个 Agent 就卡住了。Harness 支持给工具设置超时但更稳妥的做法是在工具函数内部用timeout参数控制外部调用。比如用requests的时候始终传timeout5。超时后返回“查询超时请稍后重试”让模型决定是重试还是告知用户。5.5 常见问题速查表现象可能原因排查方向解决手段模型不调工具提示不够强检查 system prompt 和 docstring强化描述设置 tool_choice参数类型错误注解不清晰检查类型注解和 docstring明确类型函数内校验响应变慢上下文过长查看 token 消耗压缩上下文精简返回值工具超时外部服务慢检查外部 API 响应时间设置超时返回友好错误重复调用工具上下文截断检查历史是否丢失调整压缩策略保留关键信息无限循环max_iterations 过大查看迭代次数调小 max_iterations5.6 几个我踩过的坑坑一工具函数有副作用。我写过一个“发送邮件”的工具结果模型在一次对话里调用了三次用户收到三封邮件。后来改成“生成邮件草稿”加“确认发送”两步由用户确认后才真正发送。有副作用的工具一定要加确认机制。坑二docstring 写得太简略。早期我写工具描述就一句话结果模型经常在不需要的时候调用。后来把“什么时候用”“什么时候不用”都写清楚准确率明显提升。坑三忽略异步工具的阻塞问题。在异步模式下如果工具函数是同步的且执行时间长会阻塞整个事件循环。解决办法是用asyncio.to_thread包装同步工具或者直接写成异步函数。坑四没有监控工具调用成功率。上线后一段时间才发现某个工具因为外部 API 变更一直失败但模型默默降级处理了用户没感知问题被掩盖了很久。一定要记录每次工具调用的输入、输出和耗时。6. 生产化部署的几点经验6.1 可观测性不能省Agent 的行为不像传统程序那样确定出问题时很难复现。我的做法是记录三类日志每次模型调用的完整请求和响应、每次工具调用的参数和结果、每轮对话的迭代次数和总耗时。这些日志在排查“为什么模型这次没调工具”这类问题时非常关键。如果不想自己搭日志系统Harness 支持接入标准的可观测性工具通过回调或事件钩子的方式把运行数据导出。具体接入方式参考官方文档的 observability 章节。6.2 灰度发布与回滚Agent 的提示词和工具集变更影响面可能很大。建议用配置中心管理 system prompt 和工具开关支持不改代码就调整。新版本先小流量灰度观察工具调用成功率、用户满意度等指标确认没问题再全量。6.3 成本控制Agent 的成本主要来自模型调用。工具调用越多轮次越多成本越高。控制成本的手段包括精简工具返回值、设置合理的 max_iterations、对简单问题走规则而不是模型、缓存高频查询结果。我见过一个项目光是精简工具返回值这一项就把平均 token 消耗降了 40%。6.4 安全边界Agent 能调用工具就意味着它能产生实际影响。工具集里如果有写操作下单、退款、发消息一定要加权限校验和人工确认。另外用户输入可能包含注入攻击试图让模型调用不该调用的工具。Harness 本身不做输入过滤这层需要你在业务侧实现。7. 我对这个 SDK 的实际使用体会用了一段时间下来Harness SDK 最大的价值是把 Agent 开发从“造轮子”变成了“搭积木”。以前写 Agent一半时间在调循环一半时间在调工具解析。现在这两块基本不用管精力可以放在工具设计和提示词优化上。它也不是银弹。如果你的场景非常特殊比如需要自定义的循环控制逻辑或者要接入非标准的模型接口可能还是得自己写。但对于大多数“模型加工具”的 Agent 场景它确实能省下大量时间。最后分享一个小技巧先用最简单的工具集跑通再逐步加工具。我一开始就把十几个工具全塞进去结果模型选择困难准确率很低。后来精简到三个核心工具跑稳了再一个一个加每次加完观察一段时间问题定位起来容易得多。工具不是越多越好每个工具都会增加模型的认知负担能合并的尽量合并能去掉的果断去掉。
告别手写Agent循环：Strands Harness SDK实战指南
1. 为什么“手写 Agent 循环”正在变成一种负担如果你最近半年在折腾 AI Agent大概率经历过这个阶段一开始兴致勃勃地写一个while True循环把用户输入塞进 prompt调一次模型解析返回判断要不要调工具调完再把结果塞回去循环往复。第一版跑通的时候特别有成就感感觉自己掌握了 Agent 的“内核”。但很快问题就来了。工具调用格式在不同模型之间不统一有的返回 JSON有的返回 XML 标签有的干脆把参数写在自然语言里多轮对话的上下文管理越来越乱token 消耗像流水一样错误处理基本靠 try-except 硬扛模型偶尔抽风返回个空字符串整个循环就卡死了想加个流式输出、加个重试、加个可观测性代码量直接翻倍。到最后你会发现真正跟业务相关的逻辑可能只占 20%剩下 80% 都在处理 Agent 运行时的脏活累活。这就是Strands Agents Harness SDK想解决的问题。它的核心主张非常直接把 Agent 的运行时循环、工具编排、上下文管理、错误恢复这些通用能力封装成一个 SDK你只需要定义“我要什么工具”“我用哪个模型”“我的系统提示是什么”剩下的交给 Harness 去跑。标题里说的“一行代码拿到生产级 Agent”虽然有点营销色彩但它确实把 Agent 从 demo 到可用的距离压缩了很多。这篇文章我会从实际使用角度出发拆解这个 SDK 的设计思路、核心概念、上手步骤以及我在接入过程中踩过的坑。适合已经了解 Agent 基本概念、动手写过至少一个 Agent demo、但被运行时细节折磨过的开发者。如果你还在纠结“什么是 Agent”建议先补一下基础再来看这篇。2. Strands Agents Harness SDK 的整体设计与思路拆解2.1 它到底封装了什么要理解这个 SDK 的价值得先看清楚一个 Agent 运行时到底包含哪些部分。我把它拆成四层第一层是模型调用层负责跟 LLM 交互处理请求构造、响应解析、流式输出、重试和超时。第二层是工具编排层负责把工具的定义转换成模型能理解的格式解析模型的工具调用意图执行工具把结果回传。第三层是上下文管理层负责维护对话历史、裁剪超长上下文、管理 system prompt 和 few-shot 示例。第四层是循环控制层也就是那个经典的“思考-行动-观察”循环决定什么时候继续调工具、什么时候结束、什么时候触发人工介入。手写 Agent 的时候这四层全部混在一个函数里。Harness SDK 的做法是把这四层拆开每一层都有明确的抽象和默认实现同时保留扩展点。你不需要关心它内部怎么解析工具调用但如果你想换一种解析策略也能通过接口替换。这种设计的好处是关注点分离。业务开发者只需要写工具函数和系统提示运行时的事情交给 SDK。而框架开发者可以针对某一层做优化不影响其他层。2.2 为什么叫“Harness”Harness 这个词在工程领域通常指“线束”或“约束框架”在软件里常用来表示一套把零散组件组织起来、提供统一运行环境的骨架。这里用 Harness 而不是 Framework我觉得是有意为之的。Framework 通常意味着“你要按我的方式来”侵入性比较强你得继承某个基类、实现某个接口、遵循某种目录结构。而 Harness 更像是一个“外挂的运行时”你的工具函数还是普通的 Python 函数你的业务逻辑还是普通的业务逻辑Harness 只是在外面套了一层负责调度和编排。这个区别在实际使用中很关键。我试过一些 Agent 框架光是让一个已有的函数变成“工具”就要写一堆装饰器和 schema 定义。Harness 的思路是尽量利用 Python 原生的类型注解和 docstring减少样板代码。这一点后面讲工具定义的时候会具体说。2.3 方案选型背后的取舍任何 SDK 的设计都是取舍。Harness 在几个关键点上做了明确选择选择一以代码为中心而不是以配置为中心。有些 Agent 平台走的是低代码路线用 YAML 或可视化界面定义 Agent。Harness 坚持用 Python 代码定义一切。这个选择的理由是Agent 的逻辑往往需要跟现有系统深度集成纯配置的方式在复杂场景下会很快遇到天花板。用代码定义意味着你可以用 IDE 的补全、类型检查、单元测试工程化程度更高。选择二默认同步支持异步。很多新出的 Agent 框架一上来就 all-in async。Harness 的默认接口是同步的异步作为可选。这个选择对新手友好因为同步代码更容易调试。但如果你要处理高并发场景就得切到异步模式这时候要注意工具函数也得是异步的否则会阻塞事件循环。选择三工具即函数不强制 schema。这是我觉得最舒服的一点。你写一个普通的 Python 函数加上类型注解和 docstringHarness 会自动提取参数 schema 给模型。不需要手写 JSON Schema不需要维护两套定义。代价是 docstring 的质量直接影响模型调用工具的准确率所以写 docstring 的时候不能偷懒。3. 核心概念与实操要点解析3.1 Agent、Tool、Model 三个核心对象Harness SDK 的核心概念不多主要就三个Agent、Tool、Model。Agent 是编排中心它持有 Model 和一组 Tool负责驱动整个循环。你创建一个 Agent 的时候至少要传一个 Model 和一个系统提示。Tool 是可选的但实际项目里基本都会用到。Tool 在 Harness 里就是一个 Python 函数。它可以是同步的也可以是异步的。函数的名字、参数类型注解、docstring 会被自动转换成模型能理解的工具描述。这里有个细节参数类型注解必须准确因为模型会根据类型来决定传字符串还是数字。如果你把count: int写成count模型可能会传3而不是3然后在你的函数里报类型错误。Model 是模型调用的抽象。Harness 支持多种模型提供商通过统一的接口调用。切换模型的时候理论上只需要换一个 Model 实例Agent 的代码不用动。但实际使用中不同模型对工具调用的支持程度不一样有些模型在复杂工具场景下表现明显更好这个后面会讲。3.2 工具定义的三个关键细节工具定义看起来简单但有几个细节直接决定 Agent 能不能稳定工作。第一个细节是 docstring 的写法。Harness 会把 docstring 作为工具描述传给模型。模型根据这个描述来判断“什么时候该用这个工具”。所以 docstring 不能只写“查询天气”要写清楚“当用户询问某个城市的当前天气、温度、湿度时使用此工具”。描述越具体模型误用的概率越低。第二个细节是参数命名。参数名要语义化不要用a、b、x这种。模型看到city和date能理解看到arg1和arg2就只能猜。如果参数有枚举值最好在 docstring 里列出来比如“unit 参数可选 celsius 或 fahrenheit”。第三个细节是返回值。工具函数的返回值会被序列化后塞回上下文。如果返回一个巨大的字典会迅速吃掉 token。我的经验是工具返回值尽量精简只返回模型需要的信息。如果确实需要返回大量数据考虑返回一个摘要加一个引用 ID让模型按需再查。下面是一个工具定义的示例展示了上面几个细节def get_weather(city: str, unit: str celsius) - str: 查询指定城市的当前天气情况。 当用户询问某个城市的天气、温度、是否下雨等问题时使用此工具。 Args: city: 城市名称例如 北京、上海、深圳。 unit: 温度单位可选 celsius 或 fahrenheit默认为 celsius。 Returns: 包含温度、天气状况和湿度的简要描述。 # 实际实现省略 return f{city} 当前 25 度晴湿度 60%这个函数没有任何装饰器Harness 会自动识别它作为工具。参数类型注解和 docstring 就是全部的“schema”。3.3 上下文管理的默认策略与调整Harness 默认会维护完整的对话历史包括用户消息、模型回复、工具调用和工具结果。这在短对话里没问题但对话一长token 就会爆。SDK 提供了几种上下文管理策略。默认策略是“保留最近 N 轮”超过的部分会被截断。这个 N 可以配置。但简单的截断有个问题如果被截断的部分包含重要的工具调用结果模型可能会“失忆”重复调用同一个工具。更稳妥的做法是摘要式压缩当上下文超过阈值时调用一次模型把历史对话压缩成摘要保留关键信息。Harness 支持自定义压缩策略你可以实现一个压缩函数在上下文超限时被调用。我的建议是在开发阶段先用默认策略快速跑通流程。上线前一定要根据实际对话长度分布调整阈值和压缩策略。我见过一个案例客服 Agent 在对话到第 15 轮左右开始出现“重复问用户已经回答过的问题”排查下来就是上下文截断把早期信息丢了。3.4 错误处理与重试机制Agent 运行中最常见的错误有三类模型调用失败超时、限流、工具执行失败参数错误、外部服务不可用、模型返回格式异常工具调用解析失败。Harness 对这三类错误有不同的默认处理。模型调用失败默认会重试重试次数和退避策略可配置。工具执行失败默认会把错误信息作为工具结果返回给模型让模型决定下一步。模型返回格式异常默认会尝试修复修复失败则终止本轮。这里有个实操心得工具函数内部一定要自己处理可预期的异常不要把异常抛给 Harness。比如调用外部 API 的时候如果 API 返回 404你应该在工具函数里捕获返回一个“未找到”的描述而不是让异常冒泡。因为异常冒泡后Harness 会把堆栈信息塞回上下文既浪费 token又可能让模型困惑。4. 从零搭建一个可用的 Agent完整实操流程4.1 环境准备与依赖安装先确认 Python 版本。Harness SDK 要求 Python 3.9 以上我建议直接用 3.11 或 3.12类型注解的支持更完整运行速度也更好。如果你还在用 3.8先升级不然后面会遇到一些奇怪的兼容问题。安装方式很直接pip install strands-agents-harness如果你用虚拟环境强烈建议先创建再安装python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install strands-agents-harness安装完成后验证一下import strands_harness print(strands_harness.__version__)能打印出版本号就说明装好了。如果报ModuleNotFoundError检查一下是不是装到了全局环境而不是虚拟环境。4.2 配置模型接入Harness 支持多种模型提供商。配置方式通常是通过环境变量传 API Key然后在代码里指定模型名称。以常见的接入方式为例import os from strands_harness import Agent, Model os.environ[MODEL_API_KEY] your-api-key-here model Model( provideryour-provider, model_nameyour-model-name, temperature0.3, max_tokens2048 )这里有几个参数值得说明。temperature在 Agent 场景下建议设低一点0.2 到 0.4 之间比较合适因为工具调用需要稳定性太高的温度会让模型“发挥创意”选错工具或编造参数。max_tokens要根据你的工具返回长度来定如果工具返回内容较长这个值要相应调大否则模型可能还没输出完就被截断。注意API Key 不要硬编码在代码里用环境变量或密钥管理服务。我见过有人把 Key 提交到公开仓库结果被刷爆额度。4.3 定义你的第一批工具工具的定义前面讲过这里给一个更完整的例子包含两个工具一个查询订单状态一个计算退款金额。def query_order_status(order_id: str) - str: 根据订单号查询订单的当前状态。 当用户询问订单进度、是否发货、物流信息时使用此工具。 Args: order_id: 订单号通常是 12 位数字字符串。 Returns: 订单状态的文字描述包括下单时间、当前状态和预计送达时间。 # 模拟查询 mock_orders { 123456789012: 已发货预计明天送达, 987654321098: 待付款请尽快完成支付 } return mock_orders.get(order_id, 未找到该订单请确认订单号是否正确) def calculate_refund(order_id: str, reason: str) - str: 计算指定订单的退款金额。 当用户明确要求退款、询问能退多少钱时使用此工具。 Args: order_id: 订单号。 reason: 退款原因例如 质量问题、七天无理由、发错货。 Returns: 退款金额和退款政策的说明。 # 模拟计算 return f订单 {order_id} 因 {reason} 可退款 199.00 元将在 3 个工作日内原路返回注意两个工具的 docstring 都写清楚了“什么时候用”。这是模型选择工具的主要依据。如果你发现模型经常选错工具第一件事就是回去改 docstring把使用场景写得更具体。4.4 组装 Agent 并跑通第一轮对话把 Model 和 Tool 组装起来from strands_harness import Agent, Model model Model(provideryour-provider, model_nameyour-model-name) agent Agent( modelmodel, tools[query_order_status, calculate_refund], system_prompt你是一个电商客服助手。用户询问订单相关问题时先查询订单状态再回答。涉及退款时先计算退款金额再告知用户。回答要简洁友好。 ) response agent.run(我的订单 123456789012 到哪了) print(response)跑起来之后你会看到 Agent 自动调用了query_order_status然后把结果整理成自然语言回复。整个过程你只写了工具函数和系统提示循环、解析、回传都是 Harness 做的。4.5 加入流式输出与多轮对话实际产品里用户不会只问一句。多轮对话需要维护会话状态。Harness 的 Agent 实例可以复用每次run会基于之前的上下文继续response1 agent.run(我的订单 123456789012 到哪了) print(response1) response2 agent.run(那我想退款质量有问题) print(response2)第二轮对话里模型能“记得”上一轮的订单号直接调用calculate_refund不需要用户重复提供。流式输出在需要实时展示的场景很有用for chunk in agent.stream(帮我查一下订单 123456789012): print(chunk, end, flushTrue)流式模式下工具调用的过程也会以事件形式暴露出来你可以据此在前端展示“正在查询订单...”这样的状态提示。4.6 参数计算与配置调优Agent 上线前有几个参数需要根据实际场景调优。我整理了一个对照表参数默认值建议范围调整依据temperature0.70.2-0.4工具调用场景需要稳定性max_tokens10242048-4096根据工具返回长度调整max_iterations105-15防止无限循环复杂任务可调大retry_count32-5外部服务不稳定时调大context_window自动根据模型定留 20% 余量给输出max_iterations这个参数特别重要。它限制了一轮对话里模型最多调用多少次工具。设太小复杂任务跑不完设太大模型可能陷入死循环。我的经验是先设 10观察实际运行中的迭代次数分布再调整。5. 常见问题与排查技巧实录5.1 模型不调用工具直接编造答案这是最常见的问题。用户问“订单到哪了”模型不调query_order_status直接回复“您的订单正在路上”。原因是系统提示或工具描述不够强模型觉得可以直接回答。解决办法有三个层次。第一在系统提示里明确写“涉及订单状态必须调用 query_order_status 工具不得凭记忆回答”。第二在工具 docstring 里强调“必须使用此工具获取实时数据”。第三如果还是不行考虑在 Agent 配置里设置tool_choicerequired强制模型在特定场景下必须调用工具。5.2 工具参数传错类型模型把order_id传成了数字123456789012而不是字符串123456789012。如果你的函数注解是strHarness 会尝试转换但转换失败就会报错。预防方法是在 docstring 里明确参数类型比如“order_id: 订单号12 位数字字符串”。另外工具函数内部对参数做一次校验如果类型不对返回一个友好的错误描述让模型自己纠正。5.3 上下文过长导致响应变慢对话轮次多了之后每次请求都要带上完整历史token 消耗大响应也慢。除了前面说的压缩策略还有一个技巧把不必要的信息从工具返回值里去掉。比如查询订单返回了 20 个字段但模型只需要状态和预计送达时间那就只返回这两个。工具返回值精简上下文增长速度会明显下降。5.4 工具执行超时外部 API 响应慢工具函数卡住整个 Agent 就卡住了。Harness 支持给工具设置超时但更稳妥的做法是在工具函数内部用timeout参数控制外部调用。比如用requests的时候始终传timeout5。超时后返回“查询超时请稍后重试”让模型决定是重试还是告知用户。5.5 常见问题速查表现象可能原因排查方向解决手段模型不调工具提示不够强检查 system prompt 和 docstring强化描述设置 tool_choice参数类型错误注解不清晰检查类型注解和 docstring明确类型函数内校验响应变慢上下文过长查看 token 消耗压缩上下文精简返回值工具超时外部服务慢检查外部 API 响应时间设置超时返回友好错误重复调用工具上下文截断检查历史是否丢失调整压缩策略保留关键信息无限循环max_iterations 过大查看迭代次数调小 max_iterations5.6 几个我踩过的坑坑一工具函数有副作用。我写过一个“发送邮件”的工具结果模型在一次对话里调用了三次用户收到三封邮件。后来改成“生成邮件草稿”加“确认发送”两步由用户确认后才真正发送。有副作用的工具一定要加确认机制。坑二docstring 写得太简略。早期我写工具描述就一句话结果模型经常在不需要的时候调用。后来把“什么时候用”“什么时候不用”都写清楚准确率明显提升。坑三忽略异步工具的阻塞问题。在异步模式下如果工具函数是同步的且执行时间长会阻塞整个事件循环。解决办法是用asyncio.to_thread包装同步工具或者直接写成异步函数。坑四没有监控工具调用成功率。上线后一段时间才发现某个工具因为外部 API 变更一直失败但模型默默降级处理了用户没感知问题被掩盖了很久。一定要记录每次工具调用的输入、输出和耗时。6. 生产化部署的几点经验6.1 可观测性不能省Agent 的行为不像传统程序那样确定出问题时很难复现。我的做法是记录三类日志每次模型调用的完整请求和响应、每次工具调用的参数和结果、每轮对话的迭代次数和总耗时。这些日志在排查“为什么模型这次没调工具”这类问题时非常关键。如果不想自己搭日志系统Harness 支持接入标准的可观测性工具通过回调或事件钩子的方式把运行数据导出。具体接入方式参考官方文档的 observability 章节。6.2 灰度发布与回滚Agent 的提示词和工具集变更影响面可能很大。建议用配置中心管理 system prompt 和工具开关支持不改代码就调整。新版本先小流量灰度观察工具调用成功率、用户满意度等指标确认没问题再全量。6.3 成本控制Agent 的成本主要来自模型调用。工具调用越多轮次越多成本越高。控制成本的手段包括精简工具返回值、设置合理的 max_iterations、对简单问题走规则而不是模型、缓存高频查询结果。我见过一个项目光是精简工具返回值这一项就把平均 token 消耗降了 40%。6.4 安全边界Agent 能调用工具就意味着它能产生实际影响。工具集里如果有写操作下单、退款、发消息一定要加权限校验和人工确认。另外用户输入可能包含注入攻击试图让模型调用不该调用的工具。Harness 本身不做输入过滤这层需要你在业务侧实现。7. 我对这个 SDK 的实际使用体会用了一段时间下来Harness SDK 最大的价值是把 Agent 开发从“造轮子”变成了“搭积木”。以前写 Agent一半时间在调循环一半时间在调工具解析。现在这两块基本不用管精力可以放在工具设计和提示词优化上。它也不是银弹。如果你的场景非常特殊比如需要自定义的循环控制逻辑或者要接入非标准的模型接口可能还是得自己写。但对于大多数“模型加工具”的 Agent 场景它确实能省下大量时间。最后分享一个小技巧先用最简单的工具集跑通再逐步加工具。我一开始就把十几个工具全塞进去结果模型选择困难准确率很低。后来精简到三个核心工具跑稳了再一个一个加每次加完观察一段时间问题定位起来容易得多。工具不是越多越好每个工具都会增加模型的认知负担能合并的尽量合并能去掉的果断去掉。
