AI Agent 工程师入门指南：从原理到代码实战

m0_73571447

44人浏览 · 2026-08-21 16:49:33

m0_73571447 · 2026-08-21 16:49:33 发布

1. 引言：什么是 AI Agent

AI Agent（智能体）是以大语言模型（LLM）为核心，能够感知环境、自主规划、调用工具并执行任务以达成目标的程序系统。与传统单轮问答不同，Agent 具备记忆、推理和行动能力，可以完成多步骤复杂任务。

本文面向零基础或初级开发者，从核心概念讲起，逐步深入到代码实战，帮助你建立 AI Agent 工程师所需的知识体系和动手能力。

2. 核心概念与架构

一个完整的 AI Agent 通常由以下核心模块组成：

大语言模型（LLM）：负责理解指令、推理决策和生成文本。
规划（Planning）：将复杂任务拆解为可执行的子步骤。
记忆（Memory）：保存对话历史、任务状态和长期知识。
工具调用（Tool Use）：通过函数调用访问外部 API、数据库或代码执行环境。
行动与反馈（Action & Feedback）：执行动作并根据结果调整下一步计划。

下图展示了 Agent 的基本工作流程：

flowchart TD
    A[用户输入] --> B[LLM 理解与规划]
    B --> C{是否需要工具?}
    C -- 是 --> D[调用工具/API]
    D --> E[获取结果]
    E --> B
    C -- 否 --> F[生成最终回复]
    F --> G[输出给用户]

3. 环境准备

在开始编码前，请确保本地环境满足以下要求：

Python 3.10 或更高版本
一个 OpenAI 兼容的 API Key（或使用本地模型如 Ollama）
安装必要的 Python 包

执行以下命令安装依赖：

pip install openai python-dotenv

在项目根目录创建 .env 文件，写入你的 API Key：

OPENAI_API_KEY=sk-你的密钥
OPENAI_BASE_URL=https://api.openai.com/v1

4. 第一个 Agent：简单的对话助手

我们先从最基础的对话助手开始，理解 LLM 调用的基本流程。

import os
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
client = OpenAI(
api_key=os.getenv("OPENAI_API_KEY"),
base_url=os.getenv("OPENAI_BASE_URL"),
)
def chat(prompt: str) -> str:
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "你是一个乐于助人的 AI 助手。"},
{"role": "user", "content": prompt},
],
)
return response.choices[0].message.content
if name == "main":
print(chat("请用一句话介绍你自己"))

运行上述代码，你会得到模型返回的自我介绍。这是所有 Agent 的基础——先学会与 LLM 对话。

5. 让 Agent 学会调用工具

真正的 Agent 需要调用外部工具。OpenAI 提供了 Function Calling 机制，让模型可以输出结构化调用指令。下面我们实现一个能查询天气的 Agent。

import json
import os
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
模拟天气查询工具
def get_weather(city: str) -> str:
weather_data = {
"北京": "晴，25°C",
"上海": "多云，28°C",
"广州": "小雨，30°C",
}
return weather_data.get(city, "暂无该城市数据")
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的天气",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称"}
},
"required": ["city"],
},
},
}
]
def run_agent(user_input: str) -> str:
messages = [{"role": "user", "content": user_input}]
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
tools=tools,
tool_choice="auto",
)
msg = response.choices[0].message
if msg.tool_calls:
# 执行工具调用
for tool_call in msg.tool_calls:
args = json.loads(tool_call.function.arguments)
result = get_weather(args["city"])
messages.append(msg)
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": result,
})
# 将工具结果返回给模型生成最终回答
final = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
)
return final.choices[0].message.content
return msg.content
if name == "main":
print(run_agent("北京今天天气怎么样？"))

这段代码演示了 Agent 的核心循环：模型判断需要调用工具，我们执行工具并返回结果，模型再基于结果生成最终回答。

6. 使用 LangChain 构建 Agent

LangChain 是目前最流行的 Agent 开发框架之一，它封装了工具调用、记忆管理和链式调用等复杂逻辑。首先安装依赖：

pip install langchain langchain-openai

下面用 LangChain 快速构建一个带记忆的 Agent：

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain.tools import tool
from langchain.memory import ConversationBufferMemory
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
load_dotenv()
@tool
def add(a: float, b: float) -> float:
"""计算两个数字的和"""
return a + b
@tool
def multiply(a: float, b: float) -> float:
"""计算两个数字的乘积"""
return a * b
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
prompt = ChatPromptTemplate.from_messages([
("system", "你是一个数学计算助手，请使用工具完成计算。"),
MessagesPlaceholder(variable_name="chat_history"),
("human", "{input}"),
MessagesPlaceholder(variable_name="agent_scratchpad"),
])
memory = ConversationBufferMemory(
memory_key="chat_history",
return_messages=True,
)
agent = create_tool_calling_agent(llm, [add, multiply], prompt)
executor = AgentExecutor(agent=agent, tools=[add, multiply], memory=memory, verbose=True)
if name == "main":
print(executor.invoke({"input": "请计算 3 加 5 等于多少？"}))
print(executor.invoke({"input": "再帮我算一下刚才的结果乘以 4 是多少？"}))

注意第二个问题用到了「刚才的结果」，这正是记忆模块在起作用。LangChain 自动维护了对话历史，让 Agent 具备多轮上下文理解能力。

7. 实战项目：自动研究报告生成器

下面我们综合运用所学知识，构建一个能自动搜索资料并生成研究报告的 Agent。这个项目包含搜索工具、内容总结和报告生成三个环节。

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain.tools import tool
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
load_dotenv()
模拟搜索工具（实际可接入 SerpAPI 或 Bing Search）
@tool
def search_web(query: str) -> str:
"""搜索互联网获取最新信息"""
# 这里用模拟数据代替真实搜索
database = {
"AI Agent": "AI Agent 是 2025 年最热门的 AI 应用方向，市场规模预计达 500 亿美元。",
"大模型": "大语言模型参数规模持续增长，多模态成为新趋势。",
"自动驾驶": "L4 级自动驾驶进入商业化试点阶段。",
}
return database.get(query, f"关于 {query} 的搜索结果：暂无详细数据，建议查阅最新行业报告。")
@tool
def summarize(text: str) -> str:
"""对长文本进行摘要"""
# 实际项目中可调用 LLM 完成摘要
return f"摘要：{text[:50]}..."
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.3)
prompt = ChatPromptTemplate.from_messages([
("system", "你是一名资深行业分析师，请基于工具返回的资料撰写结构清晰、数据详实的研究报告。"),
("human", "{input}"),
MessagesPlaceholder(variable_name="agent_scratchpad"),
])
agent = create_tool_calling_agent(llm, [search_web, summarize], prompt)
executor = AgentExecutor(agent=agent, tools=[search_web, summarize], verbose=True)
if name == "main":
result = executor.invoke({
"input": "请研究 AI Agent 行业的发展现状，并生成一份 500 字左右的报告。"
})
print(result["output"])

运行后，Agent 会先调用搜索工具获取资料，再调用摘要工具整理信息，最后生成完整报告。你可以把 search_web 替换为真实的搜索 API，让 Agent 具备联网能力。

8. 进阶：多 Agent 协作

复杂任务往往需要多个 Agent 分工协作。下面演示一个「项目经理 + 程序员 + 测试员」的多 Agent 系统。

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain.tools import tool
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
load_dotenv()
@tool
def write_code(requirement: str) -> str:
"""根据需求编写 Python 代码"""
return f"def solution():\n    # 实现：{requirement}\n    return '完成'"
@tool
def run_tests(code: str) -> str:
"""对代码执行测试"""
return "测试通过，无错误。"
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
def create_agent(system_prompt: str, tools: list):
prompt = ChatPromptTemplate.from_messages([
("system", system_prompt),
("human", "{input}"),
MessagesPlaceholder(variable_name="agent_scratchpad"),
])
agent = create_tool_calling_agent(llm, tools, prompt)
return AgentExecutor(agent=agent, tools=tools, verbose=True)
三个角色
manager = create_agent(
"你是项目经理，负责拆解任务并分派给程序员。",
[write_code],
)
programmer = create_agent(
"你是资深程序员，负责编写高质量代码。",
[write_code],
)
tester = create_agent(
"你是测试工程师，负责验证代码质量。",
[run_tests],
)
if name == "main":
# 模拟协作流程
task = "实现一个计算斐波那契数列的函数"
plan = manager.invoke({"input": f"请拆解任务：{task}"})
code = programmer.invoke({"input": f"请编写代码：{task}"})
test_result = tester.invoke({"input": f"请测试代码：{code['output']}"})
print("项目经理计划：", plan["output"])
print("程序员产出：", code["output"])
print("测试结果：", test_result["output"])

多 Agent 协作的核心思想是「职责分离」：每个 Agent 只负责一个专业领域，通过工具和消息传递完成整体任务。实际生产环境中，你可以用消息队列或工作流引擎来编排这些 Agent。

9. 常见问题与调试技巧

开发 Agent 过程中，你可能会遇到以下常见问题：

问题	可能原因	解决方案
模型不调用工具	工具描述不清晰	在工具 description 中写清楚用途和参数含义
工具返回格式错误	JSON 解析失败	用 try-except 包裹解析逻辑，打印原始返回
Agent 陷入死循环	缺少终止条件	设置最大迭代次数（max_iterations）
上下文过长	记忆无限累积	使用滑动窗口或摘要压缩历史