实用提示：培养熟练的代理
《实用笔记》操作指南：培养熟练的代理——针对采用该模式的团队提供的合同、校验机制以及即用代码模块。
可将此内容视为《构建熟练的智能体》中理念面向操作员的优化版本：清晰的阶段划分、有序的代码模块，以及能在交接过程中保留的恢复说明。将“概览”阶段视为可量化的基准最为有效，在扩大范围之前，需记录一份最佳操作案例、一个故障实例以及回滚说明。在功能结果旁还需记录执行时间以及令牌或查询成本。提前明确成本信息，可避免在从演示环境过渡到共享环境时出现意外费用。
那么，技能究竟是什么？
在“什么是技能”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储和功能标志应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务功能的完整性。
类比说明
在类比阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都是产品的一部分，而非后续需要补充的内容。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的逻辑连接并不等同于业务功能的完整性。
在代码中
在代码编写阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 相较于冗长的脚本，更应优先选择小型且可测试的单元。当某个步骤失败时，故障原因应能明确指向单一责任方，而非复杂的流程链。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。仅靠编译时的配置并不足以确保业务的完整性。 在代码编写阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在流程从演示环境转向共享环境时出现意外账单。
skills/
└── weather-skill/
├── SKILL.md # frontmatter + instructions
---
name: weather-skill
description: Get current weather for a location. Use when the user
asks about weather, temperature, or conditions anywhere.
---
# Get weather skill
.... {other instructions here}
让我们一起构建一个轻量级工具包
在着手开发某个功能时，首先要明确相关约定：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改始终符合初始设计。 应将配置信息与应用程序代码分开存放。环境配置文件、密钥存储以及功能开关应集中管理，这样操作人员无需查看整个系统结构即可进行审计。 需为每次调用记录工具名称、参数哈希值、响应延迟以及最终结果。如果没有这些追踪信息，调试过程往往会耗费大量时间。
from dotenv import find_dotenv, load_dotenv
from langchain.agents import create_agent
from langchain.tools import tool
from langchain_openai import ChatOpenAI
_ = load_dotenv(find_dotenv())
llm = ChatOpenAI(
model="gpt-5.6-luna",
use_responses_api=True,
reasoning={"effort": "low"}, #The reasoning is medium by default so set this to l
)
@tool
def get_weather(location: str) -> str:
"""
Get the weather for a given location
"""
return f"The weather in {location} is sunny"
@tool
def get_exchange_rate(currency_from: str, currency_to: str) -> str:
"""
Get the exchange rate between two currencies
"""
return f"The exchange rate for {currency_from} to {currency_to} is 1.00"
运用技能指导工具使用
在编写“利用技能指导阶段”相关内容时，首先需列出契约：所需输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的组成部分，而非后续的优化工作。 需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试代理将陷入无止境的循环，耗费大量时间。
skills/
└── weather-skill/
├── SKILL.md
└── forex-skill/
├── SKILL.md
---
name: forex-skill
description: Get live exchange rates between two currencies. Use this whenever the user asks about currency conversion, exchange rates, how much something costs in another currency, or comparisons like "is the dollar strong right now" — even if they don't use the words "forex" or "exchange rate" explicitly (e.g. "how much is 500 SGD in yen", "should I exchange money now or wait"). Always use this instead of guessing from memory, since exchange rates move constantly and Claude's training data has no visibility into current rates.
---
# Forex Skill
Fetches the live exchange rate between two currencies and reports it back in a clear, practical format.
## Instructions
1. **Identify both currencies.** Convert casual references to standard 3-letter ISO codes before calling the tool (e.g. "dollars" → ask which dollar: USD, SGD, AUD, etc.; "yen" → JPY; "pounds" → GBP).
2. **Handle ambiguous currency names.** If the user says something like "dollars" or "pounds" without specifying which country, ask them to clarify before calling the tool — don't assume USD/GBP by default.
3. **Call the `get_exchange_rate` tool**, passing both currency codes:
```python
get_exchange_rate(currency_from="<code>", currency_to="<code>")
```
4. **If the tool call fails or returns an error**, tell the user plainly that the rate lookup failed — don't fall back to guessing a rate from memory.
5. **Call once per currency pair.** For multi-currency questions (e.g. "compare SGD to USD, EUR, and JPY"), call the tool separately for each pair.
6. **Do the math for the user.** If they gave an amount ("convert 500 SGD to JPY"), multiply it out yourself using the returned rate — don't just hand back the raw rate and leave them to calculate it.
## Output format
...
## Examples
...
实验1：文件中的技能
在完成“实验1技能”阶段时，首先需明确相关规范：所需输入、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改保持透明。 建议采用小型、可测试的单元，而非冗长的脚本。当某一步骤失败时，故障应指向单一责任模块，而非复杂的流程链。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的LLM服务。 在完成“实验1技能”阶段时，首先需明确相关规范：所需输入、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改保持透明。 在功能结果旁记录执行时间以及Token或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外费用。
from deepagents.backends import FilesystemBackend
from deepagents.middleware import FilesystemMiddleware, SkillsMiddleware
backend = FilesystemBackend(root_dir="../", virtual_mode=True)
agent = create_agent(
model=llm,
tools=[get_weather, get_exchange_rate],
middleware=[
SkillsMiddleware(backend=backend, sources=["./skills/"]),
FilesystemMiddleware(
backend=backend,
tools=["read_file"], # read_file and nothing else
system_prompt=None,
),
],
)
试一试
“试一试”阶段若被视为可度量的界面，效果会最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 将配置置于应用程序代码之外。环境文件、密钥存储和功能标志应集中存放于一处，这样操作人员无需查看整个结构即可进行审计。 保持图结构的扁平化与类型化。嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，且在中断后会导致恢复失败。
>>> agent.invoke({"messages": [HumanMessage("What is the weather in Singapore?")]})
Singapore is currently **sunny**. It's a good time for outdoor plans.
实验2：远程技能
将实验2的远程功能阶段视为可测量的界面来处理效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 同时记录正常流程和恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的一部分，而非后续的优化内容。 保持图表状态简洁且类型明确。嵌套的数据块会掩盖哪个节点编写了哪个字段的信息，还会在中断后导致流程无法继续。
from urllib.request import urlopen
from deepagents.backends import StateBackend
from deepagents.backends.utils import create_file_data
backend = StateBackend()
skill_url = "https://raw.githubusercontent.com/.../langgraph-docs/SKILL.md"
with urlopen(skill_url) as response:
skill_content = response.read().decode('utf-8')
skills_files = {
"/skills/langgraph-docs/SKILL.md": create_file_data(skill_content),
}
agent = create_agent(
model= llm
middleware=[
SkillsMiddleware(
backend=backend,
sources=["./skills/"]
),
FilesystemMiddleware(backend=backend)
]
)
result = agent.invoke(
{
"messages": [{"role": "user", "content": "What is langgraph?"}],
# seeded into the in-state filesystem. needed for the first run
"files": skills_files,
},
)
实验3：零工具
将 Experiment 3 Zero 工具阶段视为可度量的界面来使用效果最佳。在扩大范围之前，需记录一份理想运行案例、一个故障实例以及回滚说明。 相较于庞大的脚本，应优先选择小型且可测试的单元。当某一步骤出现故障时，故障原因应能明确指向某个具体责任方，而非复杂的流程链。 工具的设计应具备明确的架构规范和清晰的副作用标签。主机需要在自动批准之前知晓哪些调用会修改状态。 将 Experiment 3 Zero 工具阶段视为可度量的界面来使用效果最佳。在扩大范围之前，需记录一份理想运行案例、一个故障实例以及回滚说明。 除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
---
name: weather-skill
description: Get current weather for a location. Use when the user asks
about weather, temperature, or conditions anywhere.
---
# Get weather skill
To get the weather of a location, run:
```bash
python skills/weather-skill/scripts/get_weather.py "<location>"
```
Returns JSON with weather condition. Parse and present naturally.
Run this script on each location the user asked for, one at a time.
#skills/weather-skill/get_weather.py
def main():
location = sys.argv[1] if len(sys.argv) > 1 else None
if not location:
print(json.dumps({"error": "location argument required"}))
sys.exit(1)
print(json.dumps({"location": location, "weather": "sunny"}))
if __name__ == “__main__”:
main()
from deepagents.backend import LocalShellBackend
backend = LocalShellBackend(
root_dir=str(Path.cwd()),
virtual_mode=False,
inherit_env=True,
)
middleware = [
FilesystemMiddleware(
backend=backend,
tools=["read_file", "ls", "glob", "execute"],
system_prompt=None,
),
SkillsMiddleware(backend=backend, sources=["./skills/"]),
]
agent = create_agent(model=llm, middleware=middleware) # no tools=
等等，它真的运行了吗？
在修改代码之前，需先明确“等等，它运行了吗？”这个阶段的输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能开关都应集中存放，这样操作人员无需查看整个流程即可进行审核。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务流程的完整性。
Today's weather:
**Sydney:** Sunny
- **Melbourne:** Sunny
解决办法是记录日志——但不要输出到标准输出。
在修复阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的内容。对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的配置并不等同于业务功能的完整性。
from pathlib import Path
import logging
LOG = Path(__file__).resolve().parent.parent / "skill.log"
logging.basicConfig(
filename=LOG, level=logging.INFO,
format="%(asctime)s [pid=%(process)d] %(message)s",
)
logging.info("invoked argv=%r cwd=%s", sys.argv, os.getcwd())
22:29:55,316 [pid=45724] invoked argv=[...get_weather.py, 'Sydney'] cwd=.../notebooks
22:29:55,316 [pid=45724] resolved location=Sydney
22:29:56,795 [pid=45725] invoked argv=[...get_weather.py, 'Melbourne'] cwd=.../notebooks
22:29:56,795 [pid=45725] resolved location=Melbourne
揭示整个设计缺陷的漏洞
对于需要解释阶段的缺陷，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应指向单一责任点，而非复杂的流程链。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务功能的完整性。 对于需要解释阶段的缺陷，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 在功能结果之外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在流程从演示环境转向共享环境时出现意外账单。
。什么是virtual_mode？
在研究“什么是virtualmode”这一阶段时，首先需列出相关规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 应将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中管理，这样操作人员无需查看整个系统结构即可进行审计。 在耗时较高的步骤之后设置检查点。当操作人员重新执行后续节点时，恢复流程不应再次调用相同的大型语言模型接口。
整个设计背后的意外考量
在实现“阶段性的意外参数处理”功能时，首先需明确相关约定：所需的输入参数、成功信号，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改不会偏离原有设计。
同时记录正常流程与异常恢复流程。重试机制、人工审核环节以及错误消息处理都是产品功能的一部分，而非后续需要补充的内容。
在成本较高的操作之后设置检查点。当操作员重新尝试某个后续节点时，恢复流程不应再次调用相同的大型语言模型接口。
那么你应该构建哪一个呢？
在确定哪些部分需要进入开发阶段时，首先要写明相关规范：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改有据可依。 相比冗长的脚本，更应选择小型且易于测试的单元。当某个步骤失败时，故障应指向单一的责任模块，而非复杂的流程链。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。 在确定哪些部分需要进入开发阶段时，首先要写明相关规范：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改有据可依。 在功能结果旁记录执行时间以及Token或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外收费。
但真的需要相关技能吗？
不过，若将工作流程视为可度量的结构来处理，其实最有利于其实施。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 应将配置与应用程序代码分开。环境文件、密钥存储和功能标志应集中存放于一处，这样操作人员无需查看整个结构就能进行审计。 要保持图结构的扁平化与类型化。嵌套的数据块会掩盖是哪个节点修改了哪个字段，还会在出现中断后导致无法继续执行。
总结
“总结思考”阶段若被视为可度量的对象，效果会最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。同时将正常流程与恢复流程都记录下来。重试机制、人工审核环节以及错误处理都是产品本身的一部分，而非后续需要补充的内容。要保持数据结构的层次简单且类型明确，嵌套的数据结构会掩盖具体是哪个节点修改了哪个字段，还会在出现中断后导致流程无法继续。
操作检查清单
在处理操作检查清单阶段时，首先要明确约定：所需的输入参数、成功信号，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。
将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，定义成功判定标准，杜绝默许部分完成的情况。
在成本较高的操作之后设置检查点。当操作员重新尝试后续节点时，续程功能不应再次对同一次LLM调用收费。
锁定依赖版本，并记录用于运行演示的镜像摘要。可重复性比经验知识更为可靠。
在功能结果旁记录执行时间以及token或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外收费。
在成本较高的操作之后设置检查点。当操作员重新尝试后续节点时，续程功能不应再次对同一次LLM调用收费。
在升级整个技术栈之前，先冻结各版本，为关键路径保存标准操作记录，并确认回滚步骤。共享环境需要设置速率限制、进行租户检查，同时明确密钥轮换的责任人。与其追求华而不实的临时演示，不如注重扎实的可靠性。
关于835597b38be4的批量处理说明：不要将提供者密钥放入代码仓库，为每个会话设置令牌使用上限，并将转录内容存储在评估测试文件旁，以便后续更换模型时仍能保持可比性。
在处理强化安全措施的第0阶段时，首先明确需求规范：所需输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。优先选择小型、可测试的单元，而非冗长的脚本；当某一步骤失败时，故障应能指向单一责任点，而非复杂的流程问题。
强化安全措施细节0/781：需统计该步骤的运行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非主观判断来决定是否保留该更改。
将加固步骤1视为可测量的表面时效果最佳。在扩大范围之前，先记录一份理想的测试结果、一个故障案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
加固细节1/781：为该步骤测量实际耗时、错误类型以及令牌使用量，然后依据固定的评估标准而非主观经验来决定是否保留该变更。