AI Agent 开发入门指南

AI Agent 是能够感知环境、做出决策并执行行动的智能体。本指南介绍如何从简单的工具调用开始，逐步构建复杂的 Agent 系统。

什么是 AI Agent

与普通 LLM 应用的区别：

特性	普通 LLM 应用	AI Agent
交互方式	单轮输入输出	多轮对话、环境反馈
工具使用	无	可调用外部工具
决策能力	固定流程	动态规划和执行
记忆	上下文窗口	长期记忆、短期记忆分离
目标导向	回答问题	完成任务目标

核心组成：

Agent = LLM（大脑） + 工具（手） + 记忆（记忆） + 规划（策略）

环境准备

pip install langchain langchain-openai

第一步：工具定义

Agent 的核心能力是使用工具。先定义几个简单工具：

from langchain.tools import BaseTool
from typing import Optional, Type
from pydantic import BaseModel, Field

class CalculatorInput(BaseModel):
    expression: str = Field(description="数学表达式，如 '15 * 27'")

class CalculatorTool(BaseTool):
    name = "calculator"
    description = "执行数学计算，支持 + - * / 和括号"
    args_schema: Type[BaseModel] = CalculatorInput
    
    def _run(self, expression: str) -> str:
        try:
            # 安全计算：仅允许数字和运算符
            allowed = set('0123456789+-*/.() ')
            if not all(c in allowed for c in expression):
                return "错误：表达式包含非法字符"
            result = eval(expression)
            return str(result)
        except Exception as e:
            return f"计算错误: {str(e)}"

# 搜索工具（示例）
class SearchTool(BaseTool):
    name = "search"
    description = "搜索互联网信息"
    
    def _run(self, query: str) -> str:
        # 实际项目中接入真实搜索 API
        return f"搜索结果：关于 '{query}' 的信息..."

tools = [CalculatorTool(), SearchTool()]

工具设计原则：

1. 描述清晰：description 决定 LLM 什么时候调用该工具
2. 输入精确：使用 Pydantic 模型定义参数类型
3. 错误处理：工具内部处理异常，返回友好错误信息
4. 结果简洁：返回结果不要过长，避免占用太多上下文

第二步：ReAct Agent

ReAct（Reasoning + Acting）是最基础的 Agent 模式：

from langchain.agents import initialize_agent, AgentType
from langchain.chat_models import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

# 初始化 ReAct Agent
agent = initialize_agent(
    tools=tools,
    llm=llm,
    agent=AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True,  # 打印思维过程
    handle_parsing_errors=True
)

# 执行
result = agent.run("计算 123 乘以 456，然后搜索这个结果的相关信息")
print(result)

输出示例：

> Entering new AgentExecutor chain...
思维: 我需要先计算 123 * 456
行动: calculator
行动输入: {"expression": "123 * 456"}观察: 56088
思维: 现在搜索 56088 的相关信息
行动: search
行动输入: {"query": "56088"}观察: 搜索结果：关于 '56088' 的信息...
思绳: 我已经完成了计算和搜索，可以回答用户
最终答案: 123 乘以 456 等于 56088。搜索结果显示...

> Finished chain.

第三步：自定义 Agent 逻辑

对于复杂任务，需要更精细的控制：

from langchain.schema import AgentAction, AgentFinish
from langchain.agents import Tool, AgentExecutor
from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain

# 自定义提示词
CUSTOM_PROMPT = """你是一个有帮助的 AI 助手。你可以使用以下工具：

{tools}

使用以下格式：

思维: 你应该始终先思考
行动: 工具名称
行动输入: 工具的输入

观察结果后，你可以继续思维和行动。

当你有了最终答案，请以下面格式结束：
最终答案: 你的答案

开始！

用户问题: {input}
{agent_scratchpad}
"""

# 构建 Agent
prompt = PromptTemplate(
    template=CUSTOM_PROMPT,
    input_variables=["input", "agent_scratchpad"]
)

llm_chain = LLMChain(llm=llm, prompt=prompt)

# 使用内置的 Zero-shot ReAct 描述符
from langchain.agents.mrkl.base import ZeroShotAgent

agent = ZeroShotAgent(
    llm_chain=llm_chain,
    tools=tools,
    verbose=True
)

agent_executor = AgentExecutor.from_agent_and_tools(
    agent=agent,
    tools=tools,
    verbose=True
)

result = agent_executor.run("计算 (100 + 200) * 3")

第四步：记忆管理

Agent 需要记忆来维持多轮对话上下文：

from langchain.memory import ConversationBufferMemory

# 对话缓冲记忆
memory = ConversationBufferMemory(
    memory_key="chat_history",
    return_messages=True
)

# 带记忆的 Agent
agent = initialize_agent(
    tools=tools,
    llm=llm,
    agent=AgentType.CONVERSATIONAL_REACT_DESCRIPTION,
    memory=memory,
    verbose=True
)

# 第一轮
result1 = agent.run(input="我叫张三")
# 第二轮（能记住之前的信息）
result2 = agent.run(input="我叫什么名字？")
print(result2)  # 输出: 你叫张三

记忆类型对比：

记忆类型	特点	适用场景
Buffer	保存完整对话历史	短对话
Buffer Window	只保留最近 k 轮	中等长度对话
Summary	LLM 摘要历史	长对话
Vector Store	基于相似度检索	需要回忆远古信息
Entity	提取关键实体	多角色交互

第五步：多 Agent 协作

复杂任务需要多个专业 Agent 协作：

from langchain.agents import AgentType

# 定义专业 Agent
class ResearchAgent:
    """研究 Agent：负责信息收集和分析"""
    def __init__(self):
        self.tools = [SearchTool(), CalculatorTool()]
        self.agent = initialize_agent(
            tools=self.tools,
            llm=llm,
            agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION
        )
    
    def run(self, query: str) -> str:
        return self.agent.run(f"研究以下话题，提供详细分析: {query}")

class WriterAgent:
    """写作 Agent：负责内容创作"""
    def __init__(self):
        self.llm = llm
    
    def run(self, research: str, topic: str) -> str:
        prompt = f"基于以下研究结果，撰写一篇关于 '{topic}' 的文章：\n\n{research}"
        return self.llm.predict(prompt)

# 协作流程
class MultiAgentSystem:
    def __init__(self):
        self.researcher = ResearchAgent()
        self.writer = WriterAgent()
    
    def execute(self, topic: str) -> str:
        # 步骤 1：研究
        research = self.researcher.run(topic)
        print(f"[研究完成] {len(research)} 字符")
        
        # 步骤 2：写作
        article = self.writer.run(research, topic)
        print(f"[写作完成] {len(article)} 字符")
        
        return article

# 使用
system = MultiAgentSystem()
article = system.execute("人工智能在医疗领域的应用")
print(article)

第六步：AI Agent 框架选型指南

完成简单 ReAct、工具调用和多 Agent 原型后，下一步通常不是继续手写所有逻辑，而是根据业务目标选择合适的 Agent 框架。2025-2026 年的趋势是：框架不再只比“会不会调用工具”，而是比状态管理、可观测性、RAG 集成、低代码交付、云厂商生态与生产治理能力。

先判断：你需要 Workflow 还是 Agent？

在选框架前，先回答一个问题：任务是否真的需要 Agent 自主决策？

任务特征	更适合	原因
步骤固定、输入输出清晰、失败路径可枚举	Workflow / 工作流	可预测、可测试、成本更低
需要模型选择下一步、动态调用工具、根据观察结果调整计划	Agent	灵活性更高，适合开放式任务
涉及审批、回滚、审计、权限控制	Workflow + Agent 混合	固定边界内允许 Agent 决策
多个角色协作、研究/写作/审查分工	Multi-Agent	适合复杂认知任务，但成本和不确定性更高

实践中推荐采用“确定性 Workflow 包住非确定性 Agent”的架构：外层用工作流控制权限、状态、重试和人工审批，内层在局部步骤中让 Agent 做搜索、分析、生成或工具调用。

主流框架定位速览

框架 / 平台	核心定位	最适合场景	主要注意点
LangGraph / LangChain	有状态图编排 + LLM 应用生态	复杂多步骤 Agent、生产级流程、多工具系统	抽象较多，需要设计状态图与节点边界
LlamaIndex Workflows / Agents	数据优先的 RAG 与知识型 Agent	企业知识库、文档分析、检索增强 Agent	非 RAG 场景优势不如通用编排框架明显
CrewAI	角色驱动多 Agent 协作	研究、写作、市场分析、多角色原型	容易产生 token 冗余，复杂状态控制较弱
Microsoft AutoGen	多 Agent 对话与协作 runtime	多 Agent 研究系统、代码协作、微软生态	API 迭代较快，旧教程可能不兼容新版
OpenAI Agents SDK	OpenAI 官方轻量 Agent SDK	OpenAI-first 产品、工具调用、handoff、guardrails	供应商绑定较强，多云/私有化需谨慎
Google ADK	Gemini / Google Cloud Agent 开发工具包	Google Cloud、Vertex AI、Gemini Agent 应用	非 Google 技术栈需评估迁移成本
Pydantic AI	Python 强类型 Agent 框架	FastAPI / Pydantic 团队、结构化输出、可测试业务 Agent	生态规模小于 LangChain
Semantic Kernel	企业 AI 编排 SDK	.NET / Java / Python 企业应用、Azure OpenAI	更偏企业 SDK，社区 Agent 示例相对少
Mastra	TypeScript Agent / Workflow 框架	Node.js、Next.js、Web SaaS 产品	相对较新，长期稳定性需观察
Agno	轻量 Agent、Tools、Knowledge、Memory	快速原型、轻量多模型 Agent	企业治理和复杂编排需自行补足
Dify	低代码 LLM 应用平台	内部 AI 应用、知识库问答、快速交付	深度定制和复杂多 Agent 不如代码框架
n8n	工作流自动化 + AI 节点	AI + SaaS / CRM / 邮件 / 工单自动化	不是原生 Agent runtime
Coze	低代码 Bot / Agent 平台	快速 Bot、中文业务场景、飞书/字节生态	平台绑定和数据合规需评估

按场景快速选择

如果你的目标是……	首选	备选	选型理由
构建复杂、可恢复、可人工介入的生产级 Agent	LangGraph	AutoGen、Google ADK、Semantic Kernel	状态、分支、循环、checkpoint、human-in-the-loop 更关键
构建企业知识库 / RAG Agent	LlamaIndex	LangGraph + LangChain、Dify	数据连接、索引、检索、rerank 与知识工作流是核心
快速验证多 Agent 角色协作	CrewAI	AutoGen、LangGraph、Agno	角色 / Task / Crew 抽象直观，上手快
OpenAI 模型和工具生态优先	OpenAI Agents SDK	LangGraph、Pydantic AI	官方 SDK、tracing、guardrails、handoffs 更省心
Python 后端、重视类型和测试	Pydantic AI	LangGraph、LlamaIndex、Agno	类型安全、依赖注入、结构化输出适合工程化服务
TypeScript / Node.js 产品团队	Mastra	LangChain.js / LangGraph.js、n8n	更贴近 Web / SaaS 工程栈
.NET / Azure 企业项目	Semantic Kernel	AutoGen、Azure AI Agent Service	更贴合微软企业生态和插件化系统集成
业务团队低代码快速上线	Dify	n8n、Coze	可视化工作流、知识库和运营闭环优先
把 AI 嵌入现有业务流程	n8n	Dify、LangGraph	连接器、Webhook、SaaS 集成比 Agent 抽象更重要

生产级选型检查清单

选型时至少评估以下 10 个问题：

1. 模型与供应商：是否支持多模型、fallback、本地模型或私有化模型？是否被单一云厂商绑定？
2. 工具调用：是否支持结构化 tool calling、权限控制、超时、重试和审计？
3. 状态管理：是否支持 session state、长期记忆、checkpoint、任务恢复和回放？
4. 工作流控制：是否支持分支、循环、并行、人机协同、审批和中断恢复？
5. RAG 能力：是否内置数据连接器、metadata filtering、hybrid search、rerank、检索评估？
6. 可观测性：是否能记录 tracing、token、latency、cost、工具调用链路和失败样本？
7. 评估与测试：是否支持离线评估集、回归测试、prompt / tool 版本管理？
8. 安全与合规：是否支持权限隔离、敏感数据脱敏、prompt injection 防护和审计日志？
9. 部署形态：是否支持自托管、Docker / Kubernetes、云托管、CI/CD、灰度发布？
10. 团队匹配：团队更熟悉 Python、TypeScript、.NET 还是低代码平台？文档、社区和商业支持是否足够稳定？

推荐组合架构

架构组合	适合场景	说明
LlamaIndex + LangGraph + LangSmith	企业知识库 + 可控 Agent	LlamaIndex 管数据和检索，LangGraph 管状态和流程，LangSmith 管调试和评估
OpenAI Agents SDK + 自有业务 API	OpenAI-first SaaS	快速实现工具调用、handoff、guardrails 和 tracing
Semantic Kernel + AutoGen + Azure OpenAI	微软企业生态	适合 .NET / Azure / M365 场景下的插件化 Agent 系统
Dify + n8n	低代码交付 + 业务自动化	Dify 管 AI 应用和知识库，n8n 管 SaaS / Webhook / 工单流程
Pydantic AI + FastAPI + Postgres/pgvector	Python 生产服务	类型安全、结构化输出、可测试，适合后端 API 化交付
Mastra + Next.js + Vercel/Node 后端	TypeScript 产品团队	适合 Web 产品中嵌入 Agent、workflow 和 RAG 能力

常见误区

误区	后果	建议
一上来就做完全自主 Agent	不稳定、难评估、成本高	先做 workflow，再在关键节点引入 Agent
只看 demo，不看状态恢复和失败处理	原型能跑，生产难用	用真实失败样本测试 retry、timeout、fallback
把多 Agent 当成性能提升手段	token 成本暴涨，结果更不可控	只有在角色分工真正必要时才用多 Agent
忽略工具权限	Agent 误调用高风险 API	给工具分级、加审批、限制参数和作用域
忽略观测和评估	线上问题难复现	从第一天记录 tracing、成本、输入输出和工具调用

更系统的横向比较见 Agent 框架对比；如果任务本身是否需要 Agent 还不确定，先看 Workflow vs Agent。

完整示例：任务执行 Agent

# task_agent.py
from langchain.agents import initialize_agent, AgentType
from langchain.chat_models import ChatOpenAI
from langchain.tools import BaseTool
from typing import Type
from pydantic import BaseModel, Field

class TodoList:
    """简单的待办事项管理"""
    def __init__(self):
        self.tasks = []
    
    def add(self, task: str):
        self.tasks.append({"task": task, "done": False})
        return f"已添加: {task}"
    
    def list(self):
        if not self.tasks:
            return "暂无待办事项"
        result = []
        for i, task in enumerate(self.tasks, 1):
            status = "✅" if task["done"] else "⬜"
            result.append(f"{i}. {status} {task['task']}")
        return "\n".join(result)
    
    def complete(self, index: int):
        if 1 <= index <= len(self.tasks):
            self.tasks[index-1]["done"] = True
            return f"已完成: {self.tasks[index-1]['task']}"
        return "无效索引"

todo = TodoList()

class AddTaskInput(BaseModel):
    task: str = Field(description="待办事项描述")

class AddTaskTool(BaseTool):
    name = "add_task"
    description = "添加待办事项"
    args_schema: Type[BaseModel] = AddTaskInput
    
    def _run(self, task: str) -> str:
        return todo.add(task)

class ListTasksTool(BaseTool):
    name = "list_tasks"
    description = "列出所有待办事项"
    
    def _run(self) -> str:
        return todo.list()

class CompleteTaskInput(BaseModel):
    index: int = Field(description="事项编号")

class CompleteTaskTool(BaseTool):
    name = "complete_task"
    description = "标记事项为已完成"
    args_schema: Type[BaseModel] = CompleteTaskInput
    
    def _run(self, index: int) -> str:
        return todo.complete(index)

# 创建 Agent
tools = [AddTaskTool(), ListTasksTool(), CompleteTaskTool()]
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

agent = initialize_agent(
    tools=tools,
    llm=llm,
    agent=AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

# 测试
print(agent.run("""请帮我：
1. 添加一个任务"学习 LangChain"
2. 添加一个任务"完成 RAG 项目"
3. 列出所有任务
4. 完成第一个任务
5. 再次列出所有任务
"""))

常见问题

工具调用不稳定

问题	原因	解决
不调用工具	描述不清晰	优化 description
参数格式错误	模型输出不规范	使用 Structured Agent
无限循环	任务无法完成	设置最大迭代次数

性能优化

# 限制最大迭代次数
agent_executor = AgentExecutor.from_agent_and_tools(
    agent=agent,
    tools=tools,
    max_iterations=5,  # 最多 5 次迭代
    max_execution_time=30,  # 最多 30 秒
    early_stopping_method="generate"  # 超时后生成答案
)

进阶方向

• Plan-and-Execute：先制定计划再执行，适合复杂多步骤任务
• Self-Reflection：Agent 自我评估并改进执行策略
• Multi-Agent 框架：CrewAI、AutoGen 等专用多 Agent 框架
• Tool Learning：让 Agent 自动学习新工具的使用方法

相关页面

• AI Agents — AI Agent 技术原理与架构
• Function Calling / Tool Use — 函数调用技术详解
• RAG 系统搭建入门指南 — RAG 系统搭建入门
• LLM Wiki — LLM Wiki 知识库构建理念
• LLM-Wiki 知识库搭建指南 — 本知识库搭建指南
• 提示策略对比 — 提示策略对比
• Agent 框架对比 — Agent 开发框架对比

参考资源

• Yao et al. (2023). "ReAct: Synergizing Reasoning and Acting in Language Models."
• Wang et al. (2023). "Survey on Large Language Model based Autonomous Agents."
• LangChain Agents Documentation: https://python.langchain.com/docs/modules/agents/
• CrewAI Documentation: https://docs.crewai.com/