概述

本教程将带你从零开始构建一个实用的AI Agent——一个能够查询天气、搜索新闻、计算数学表达式的智能助手。你需要的只是一个API Key和基础的Python知识。

你将学到什么？

• AI Agent的基本工作原理
• 如何定义Agent可使用的工具
• 如何让Agent自动规划和执行任务
• 如何将Agent部署为Web服务

前置准备

pip install openai langchain langchain-community python-dotenv

第一步：定义工具

Agent的能力来自于它可以调用的"工具"。我们先定义三个基础工具：

from langchain.tools import tool
import json
import requests

@tool
def calculator(expression: str) -> str:
    """计算数学表达式的结果。输入一个数学表达式字符串，返回计算结果。"""
    try:
        result = eval(expression, {"__builtins__": {}}, {})
        return f"计算结果：{result}"
    except Exception as e:
        return f"计算错误：{str(e)}"

@tool
def search_news(query: str) -> str:
    """搜索最新新闻。输入搜索关键词，返回相关新闻摘要。"""
    # 这里使用免费API作为示例
    # 实际生产环境中可替换为新闻API
    return f"关于"{query}"的最新消息：AI技术持续推动各行业数字化转型..."

@tool
def get_weather(city: str) -> str:
    """查询城市天气。输入城市名称，返回当前天气信息。"""
    return f"{city}今日天气：晴，温度22-30℃，适合户外活动。"

# 工具集合
tools = [calculator, search_news, get_weather]

第二步：创建Agent

使用LangChain的Agent框架，将LLM和工具组合起来：

from langchain_openai import ChatOpenAI
from langchain.agents import create_openai_functions_agent, AgentExecutor
from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder

# 初始化LLM
llm = ChatOpenAI(
    model="gpt-4o",
    temperature=0,  # Agent需要确定性的输出
    api_key="your-api-key"
)

# 创建提示模板
prompt = ChatPromptTemplate.from_messages([
    ("system", """你是一个有用的AI助手，可以：
1. 使用计算器进行数学计算
2. 搜索最新新闻
3. 查询城市天气

请根据用户的需求，合理选择工具完成任务。
如果不需要工具就直接回答。
始终用中文回复。"""),
    ("user", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad"),
])

# 创建Agent
agent = create_openai_functions_agent(llm, tools, prompt)
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,  # 显示Agent的思考过程
    max_iterations=5,  # 最多迭代5次
    handle_parsing_errors=True,
)

第三步：测试Agent

让我们用几个场景测试Agent的能力：

# 场景1：单工具调用
response = agent_executor.invoke({
    "input": "帮我算一下 (135 + 246) × 7 ÷ 3 等于多少？"
})
print(response["output"])

# 场景2：信息查询
response = agent_executor.invoke({
    "input": "北京今天天气怎么样？"
})
print(response["output"])

# 场景3：多步骤任务（Agent会自动分解）
response = agent_executor.invoke({
    "input": "搜索AI Agent的最新进展，然后用一句话总结"
})
print(response["output"])

# 场景4：不需要工具的问题
response = agent_executor.invoke({
    "input": "解释一下什么是机器学习？"
})
print(response["output"])

第四步：添加记忆能力

让Agent记住之前的对话：

from langchain.memory import ConversationBufferMemory
from langchain.chains import ConversationChain

memory = ConversationBufferMemory(
    memory_key="chat_history",
    return_messages=True
)

# 更新Agent以使用记忆
from langchain.agents import create_openai_functions_agent

prompt_with_memory = ChatPromptTemplate.from_messages([
    ("system", "你是一个有用的AI助手..."),
    MessagesPlaceholder(variable_name="chat_history"),
    ("user", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad"),
])

agent_with_memory = create_openai_functions_agent(llm, tools, prompt_with_memory)
agent_executor_with_memory = AgentExecutor(
    agent=agent_with_memory,
    tools=tools,
    memory=memory,
    verbose=True,
)

第五步：部署为Web服务

将Agent封装为API接口：

from flask import Flask, request, jsonify
from flask_cors import CORS

app = Flask(__name__)
CORS(app)

@app.route("/api/agent", methods=["POST"])
def agent_endpoint():
    try:
        data = request.json
        user_input = data.get("message", "")
        session_id = data.get("session_id", "default")

        response = agent_executor_with_memory.invoke({
            "input": user_input
        })

        return jsonify({
            "success": True,
            "response": response["output"],
            "session_id": session_id
        })
    except Exception as e:
        return jsonify({
            "success": False,
            "error": str(e)
        }), 500

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000, debug=True)

进阶优化建议

1. 工具设计原则

• 单一职责：每个工具只做一件事
• 清晰的描述：docstring直接影响Agent对工具的理解
• 错误处理：工具应优雅处理异常，返回有用信息
• 输入验证：对工具参数进行安全检查

2. 安全考虑

# 永远不要这样做！
@tool
def execute_shell(command: str) -> str:
    """执行Shell命令"""
    import subprocess
    return subprocess.getoutput(command)

# 应该这样做：使用白名单限制
ALLOWED_COMMANDS = ["ls", "cat", "wc", "grep"]

@tool
def safe_file_operation(operation: str) -> str:
    """安全的文件操作"""
    cmd_parts = operation.split()
    if cmd_parts[0] not in ALLOWED_COMMANDS:
        return "不允许的操作"
    # 继续执行...

3. 成本优化

• 简单任务使用更便宜的模型（如GPT-4o-mini）
• 设置max_iterations限制Agent的循环次数
• 对常见问题实施缓存
• 监控每次调用的token消耗

4. 评估与测试

建议建立测试集，覆盖：

• 基础工具调用
• 多工具协作
• 边界情况（空输入、超长输入）
• 错误恢复（工具调用失败时的表现）

生产级Agent平台的考量

当你准备将Agent投入生产环境时，你可能需要一个专业的Agent管理平台——它应该提供：

• 统一部署：一键部署多种Agent类型
• 用量监控：实时查看Token消耗和API调用量
• 安全隔离：Agent之间互不影响
• 付费管理：统一的计费和余额体系

这些能力正是怡途Claw平台的设计初衷。

小结

构建一个AI Agent并不复杂，核心步骤就是：选择LLM → 定义工具 → 创建Agent → 部署上线。真正的挑战在于生产化——安全、稳定、可观测、成本可控。

今天就开始你的第一个Agent项目。最好的学习方式是实践。