AI编程智能体零基础搭建教程：新手入门指南

结合近期AI编程实践，深入解析当前热门的AI Coding领域。

如今开发者们已广泛使用AI编程工具——TRAE、Claude Code、Codex、Cursor等产品百花齐放。本文的目标是拆解编程智能体的底层逻辑：它们如何搭建，开发思路如何演进。我们将从零构建一个简易编程智能体，并提供Claude Code的参考提示，便于快速实践。 全文以LangChain框架为核心展开。

环境与依赖配置

首先安装核心依赖包：langchain、langchain-openai、langchain-community、python-dotenv。 在项目根目录创建.env文件，填入环境变量：

API_KEY=
BASE_URL=
MODEL_NAME=

补充说明：uv是新一代Python包管理工具，速度优于pip+venv组合；若不想引入额外工具，原生venv同样可行。 API密钥配置完毕后，即可着手开发Agent。参考格式如下：

BASE_URL=https://api.deepseek.com/v1
MODEL_NAME=deepseek-chat

注意BASE_URL使用/v1路径，遵循OpenAI兼容接口规范（/chat/completions）。

构建一个基础AI智能体

工具调用机制

简言之，智能体相较于普通LLM，核心差异在于具备环境感知能力。通过为模型绑定工具并注入动态提示词，即可构建出最小可运行的Agent。

flowchart TD
    A[用户输入] --> B[把消息历史和工具列表传给 LLM]
    B --> C{LLM 判断是否需要调用工具}
    C -- 不需要 --> D[直接生成回答]
    C -- 需要 --> E[返回 tool_calls]
    E --> F[程序根据工具名和参数执行函数/API]
    F --> G[把执行结果包装成 ToolMessage]
    G --> H[继续把结果传回 LLM]
    H --> C
    D --> I[返回给用户]

基于此流程，我们可以快速实现一个天气播报员示例——查询天气API并封装成工具，交由Agent自主决定调用时机。 为保证Agent具备上下文记忆，每次接口调用需携带完整聊天历史；工具执行结果同样需要回传。 LangChain的Message基类因此派生出四种消息类型：HumanMessage、AIMessage、SystemMessage、ToolMessage。使用时只需将相应内容包装为对应类型即可：

from langchain_core.messages import HumanMessage, AIMessage, SystemMessage, ToolMessage

messages = [
    SystemMessage(content="你是一个天气播报员，专门为人们提供天气相关咨询"),
    HumanMessage(content="给我查一下扬州这边的天气最近咋样"),
]

llm.invoke(messages)

定义工具的过程与编写普通函数无异——AI调用工具时同样传递参数并获取返回结果：

from langchain.tools import tool

@tool
# 装饰器会解析函数签名，自动生成工具描述和参数格式，让 Agent 知道怎么使用这个工具
def get_weather(city: str) -> str:
    """查询指定城市的当前天气信息。参数 city 为城市名称，如'北京'。"""
    # docstring 写清楚一些，AI 也会读
    mock_data = {
        "北京": "晴，25°C，微风",
        "上海": "多云，28°C，东南风3级",
        "广州": "小雨，30°C，湿度大"
    }
    return mock_data.get(city, f"未找到{city}的天气信息")

AI调用工具后返回的tool_calls（可能包含多个）结构示例如下：

[{
    "name": "get_weather",
    "args": {"city": "北京"},
    "id": "call_xxx",
    "type": "tool_call"
}]

掌握上述原理后，结合流程图及API文档即可手动实现完整的Agent循环：

import os
import json
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage, ToolMessage
from langchain.tools import tool

load_dotenv()

# 1. 定义天气工具
@tool
def get_weather(city: str) -> str:
    """查询指定城市的当前天气信息。参数 city 为城市名称，如'北京'。"""
    mock_data = {
        "北京": "晴，25°C，微风",
        "上海": "多云，28°C，东南风3级",
        "广州": "小雨，30°C，湿度大"
    }
    return mock_data.get(city, f"未找到{city}的天气信息")

# 2. 绑定工具，让模型知道有哪些工具可用
tools = [get_weather]
llm = ChatOpenAI(
    model=os.getenv("MODEL_NAME"),
    api_key=os.getenv("API_KEY"),
    base_url=os.getenv("BASE_URL"),
    temperature=0
).bind_tools(tools)

tool_map = {t.name: t for t in tools}

# 3. 手动实现 Agent 核心循环
def run_manual_agent(user_input: str):
    messages = [
        SystemMessage(content="你是一个天气播报员，专门为人们提供天气相关咨询"),
        HumanMessage(content=user_input)
    ]
    print(f"? User: {user_input}")

    while True:
        # A: 让 LLM 决定下一步
        response = llm.invoke(messages)
        messages.append(response)

        # B: 没有工具调用，说明已生成最终回复，退出循环
        if not response.tool_calls:
            print(f"? Assistant: {response.content}")
            break

        # C: 执行所有工具调用
        for tool_call in response.tool_calls:
            tool_name = tool_call["name"]
            tool_args = tool_call["args"]
            tool_id = tool_call["id"]

            print(f"? Tool Call: {tool_name}({json.dumps(tool_args, ensure_ascii=False)})")

            if tool_name in tool_map:
                result = tool_map[tool_name].invoke(tool_args)
            else:
                result = f"错误：未知工具 '{tool_name}'"

            print(f"? Tool Result: {result}")
            messages.append(ToolMessage(content=str(result), tool_call_id=tool_id))

if __name__ == "__main__":
    run_manual_agent("北京和上海今天天气怎么样？")

接下来可将模拟数据替换为真实API。LangChain同样提供了封装好的create_agent()，省去手动循环的繁琐。使用create_agent的精简版本如下：

import os
from dotenv import load_dotenv
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain.tools import tool

load_dotenv()

@tool
def get_weather(city: str) -> str:
    """查询指定城市的当前天气信息。
Args:
    city: 城市名称，例如 "北京"、"上海"。
Returns:
    包含该城市天气状况的字符串。
"""
    mock_weather_data = {
        "北京": "晴，气温 25°C，微风，空气质量优。",
        "上海": "多云，气温 28°C，东南风 3 级。",
        "广州": "小雨，气温 30°C，湿度较大。",
        "深圳": "阴，气温 29°C，适合室内活动。"
    }
    return mock_weather_data.get(city, f"抱歉，暂时未找到 {city} 的天气信息。")

llm = ChatOpenAI(
    model=os.getenv("MODEL_NAME"),
    api_key=os.getenv("API_KEY"),
    base_url=os.getenv("BASE_URL"),
    temperature=0
)

agent = create_agent(
    model=llm,
    tools=[get_weather],
    system_prompt="你是一个天气播报员，专门为人们提供天气相关咨询"
)

if __name__ == "__main__":
    user_question = {"messages": [{"role": "user", "content": "北京今天天气怎么样？"}]}
    result = agent.invoke(user_question)
    print(result['messages'][-1].content)

人机协作（Human-in-the-Loop）

LangChain生态中经典的酒店入住系统示例，生动诠释了“工具调用+人工介入”的基本范式。抛开代码细节，其流程如下：

graph TD
    A[客户入住说明] --> B{是否需要工具调用?}
    B -- 否 --> C[直接回复客户]
    B -- 是 --> D[调用系统 API]
    D --> E{用户确认是否正确?}
    E -- 确认 --> F[函数调用成功]
    E -- 修改 --> G[输入修改后的信息]
    G --> D

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import InMemorySa ver
from langgraph.types import interrupt, Command

load_dotenv()

# 模拟订房工具：真正执行前先 interrupt，等待用户确认
def book_room(room_id: str) -> str:
    """预订指定房间。参数 room_id 为房间号，例如'301'。"""
    human_response = interrupt({
        "message": f"AI 准备调用 book_room(room_id={room_id})，是否确认执行？",
        "room_id": room_id
    })

    if human_response["type"] == "accept":
        final_room_id = room_id
    elif human_response["type"] == "edit":
        final_room_id = human_response["room_id"]
    elif human_response["type"] == "reject":
        return "用户拒绝了本次订房操作"
    else:
        return "未知的用户反馈"

    return f"房间 {final_room_id} 已预订成功"

llm = ChatOpenAI(
    model=os.getenv("MODEL_NAME"),
    api_key=os.getenv("API_KEY"),
    base_url=os.getenv("BASE_URL"),
    temperature=0
)

checkpointer = InMemorySa ver()
agent = create_react_agent(
    model=llm,
    tools=[book_room],
    checkpointer=checkpointer
)

config = {"configurable": {"thread_id": "room-demo"}}

# 第一次运行，程序会在 interrupt 处暂停
result = agent.invoke({"messages": [{"role": "user", "content": "帮我订一下301房间"}]}, config=config)
print(result)

# 模拟用户确认
result = agent.invoke(Command(resume={"type": "accept"}), config=config)
print(result)

# 模拟用户修改：Command(resume={"type": "edit", "room_id": "302"})
# 模拟用户拒绝：Command(resume={"type": "reject"})

至此，你是否感受到了构建智能体的本质？它并不神秘，与传统业务开发思路如出一辙——原本固定的流程由模型动态路由，原本硬编码的分支替换为工具调用。大模型的引入赋予了程序灵活性，但整体仍在既定范式内运行。 下一篇将探讨AI编程智能体的初步设计思路与实际编码过程——涵盖Agent设计范式、工具设计取舍，以及从目标倒推、自顶向下的问题拆解方式。这正是AI时代需逐步建立的思维模式。 若文中存在疏漏，欢迎在评论区指正交流，与各位共同进步。

来源：互联网