AI Agent 开发教程：从概念到第一个 Agent

• @tool 装饰器的 docstring 不是给人看的，是给 LLM 看的——它靠这段文字决定什么时候调这个工具。写不清楚，LLM 就选错工具。
• agent_scratchpad 是 Agent 的"草稿纸"，存放中间推理步骤。没有它，Agent 只能单轮对话。
• verbose=True 开发阶段必开，生产环境关掉（输出太多，且暴露内部逻辑）。

添加更多工具

import requests
@tool
def search_knowledge(query: str) -> str:
    """搜索知识库获取信息。参数 query：搜索关键词。"""
    knowledge_base = {
        "RAG": "RAG（检索增强生成）是一种让大模型基于外部知识回答问题的技术。",
        "Agent": "AI Agent 是能自主规划、使用工具、执行任务的智能系统。",
        "向量数据库": "向量数据库是存储和检索向量数据的专用数据库，用于语义搜索。",
    }
    results = []
    for key, value in knowledge_base.items():
        if key in query:
            results.append(value)
    return "\n".join(results) if results else "未找到相关信息。"
@tool
def web_request(url: str) -> str:
    """发送 HTTP GET 请求获取网页内容。参数 url：目标 URL。"""
    try:
        response = requests.get(url, timeout=10)
        return response.text[:1000]  # 截断，避免把整个网页喂给 LLM
    except Exception as e:
        return f"请求失败：{e}"

多步骤推理

tools = [get_current_time, calculate, search_knowledge, web_request]
agent = create_openai_tools_agent(llm, tools, prompt)
executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,
    max_iterations=5,          # 限制最大推理步数——非常重要
    handle_parsing_errors=True  # LLM 输出格式不对时自动重试
)
result = executor.invoke({
    "input": "先告诉我现在几点，然后搜索一下 RAG 是什么，最后帮我算一下 2 的 10 次方"
})
print(result["output"])

调试技巧

# verbose=True 看推理过程，开发阶段必开
# 也可以用回调函数拿到更细粒度的信息
from langchain.callbacks import StdOutCallbackHandler
executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,
    callbacks=[StdOutCallbackHandler()]
)

错误处理

try:
    result = executor.invoke({"input": "复杂任务"})
except Exception as e:
    print(f"Agent 执行失败：{e}")

最容易踩的坑

• Agent 陷入循环：max_iterations 是安全阀，但根本原因是工具描述不够精确，LLM 无法判断该用哪个工具。
• eval() 安全风险：上面的 calculate 用了 eval()，开发演示可以，生产环境绝对不行——用户可以注入任意 Python 代码。用 ast.literal_eval 或专门的数学表达式解析库。
• 工具返回格式不稳定：LLM 对工具返回的解析依赖格式一致。如果有时返回 JSON，有时返回纯文本，Agent 会困惑。统一返回格式。
• API 调用不稳定：调用海外 API 时网络波动是常态。加重试机制，设合理的 timeout。可参考 海外 AI 工具使用指南 了解网络稳定方案。

进阶学习

• 深入学习 LangChain：LangChain 教程
• 搭建 RAG Agent：RAG 教程
• 低代码搭建 Agent：Dify 教程

---