智能体开发入门：用 Python 写出你的第一个 AI Agent

AI Agent 入门不应该从“做一个全能助手”开始，而应该从一个可控的小循环开始：用户给目标，模型判断是否调用工具，工具返回结果，模型再生成最终回答。

导读：你可以把这篇当成第一个 AI Agent 的实现流程来用。本文用 Python 写一个最小 Agent，不追求复杂框架，而是先把工具调用、错误处理和验证闭环跑通。

先定义第一个 Agent 的边界

第一个 Agent 应该满足：

条件	合格标准
任务单一	只解决一个小问题
工具少	先接 1 个只读工具
风险低	不写生产数据、不发外部消息
可验证	能用固定输入看到固定输出
可停止	工具失败时不无限重试

不要一开始做“自动订票、自动发邮件、自动改数据库”。第一个 Agent 的目标是理解机制，不是追求自动化炫技。

官方来源与核验规则

优先参考：

核验规则：模型 API、tool use 参数、消息格式和 SDK 方法可能更新，实际代码要以官方文档为准。本文示例强调结构，不保证每个模型 SDK 的最新参数完全一致。

初始化项目

mkdir my-first-agent
cd my-first-agent
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install anthropic httpx

建议把 API Key 放进环境变量：

1	export ANTHROPIC_API_KEY="sk-ant-..."

不要把 Key 写进源码或截图。

Step 1：定义一个只读工具

先写一个可预测的工具。这里用模拟天气，避免一开始被第三方 API Key、网络和限流干扰。

def get_weather(city: str) -> str:
    data = {
        "beijing": "北京：晴，25°C",
        "shanghai": "上海：多云，28°C",
    }
    return data.get(city.lower(), f"没有找到 {city} 的天气数据")

好工具有三个特点：输入清楚、输出稳定、失败可解释。

Step 2：写工具 schema

tools = [
    {
        "name": "get_weather",
        "description": "查询指定城市的当前天气。只在用户询问天气时使用。",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "城市名称，例如 Beijing 或 Shanghai"
                }
            },
            "required": ["city"]
        }
    }
]

工具描述不要写得太泛。如果 description 只写“查询信息”，模型会不知道什么时候该调用。

Step 3：实现 Agent 调用循环

最小逻辑是：先问模型，模型如果要求 tool_use，就执行工具，再把工具结果交回模型。

import os
import anthropic

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

def run_agent(user_input: str) -> str:
    messages = [{"role": "user", "content": user_input}]

    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        system="你是一个天气助手。只有需要天气信息时才调用 get_weather。",
        messages=messages,
        tools=tools,
    )

    for block in response.content:
        if block.type == "tool_use" and block.name == "get_weather":
            result = get_weather(block.input["city"])
            messages.append({"role": "assistant", "content": response.content})
            messages.append({
                "role": "user",
                "content": [{
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result,
                }],
            })
            final = client.messages.create(
                model="claude-sonnet-4-6",
                max_tokens=1024,
                system="请基于工具结果回答用户。",
                messages=messages,
                tools=tools,
            )
            return final.content[0].text

    return response.content[0].text

Step 4：验证工具调用

测试输入：

1 2	print(run_agent("北京今天热吗？")) print(run_agent("你好，介绍一下你自己"))

成功标准：

输入	预期
天气问题	调用 `get_weather`
普通问候	不调用工具
未知城市	返回可理解的失败信息

Step 5：加错误处理

第一个版本不要追求复杂，但至少要防止工具异常让整个程序崩掉：

def safe_get_weather(city: str) -> str:
    try:
        return get_weather(city)
    except Exception as exc:
        return f"weather_tool_error: {type(exc).__name__}: {exc}"