从零搭建你的第一个AI Agent

一、先搞清楚：AI Agent 到底是什么？

很多教程上来就贴代码，但如果你不理解 Agent 的核心思想，代码写完了也是一头雾水。

1.1 普通 LLM 调用 vs Agent

普通 LLM 调用是这样的：

代码块

Plain Text

用户输入 → 大模型 → 输出结果

一问一答，模型不会主动做任何事，你问什么它答什么，仅此而已。

AI Agent 是这样的：

代码块

Plain Text

用户给目标 → Agent 自主规划步骤 → 调用工具执行 → 观察结果 → 继续规划 → ... → 完成目标

🔎

Agent 的核心在于一个循环：思考（Think）→ 行动（Act）→ 观察（Observe），不断迭代，直到任务完成。

这个循环有个专业名字，叫 ReAct（Reasoning + Acting），是目前最主流的 Agent 范式。

1.2 Agent 的三个核心组件

一个完整的 Agent 由三部分组成：

飞书文档 - 图片

#COexdeKFaazx text { white-space: pre; }#COexdeKFaazx .fb0 { stroke: var(--N900-FG, 0.15); }#COexdeKFaazx .fb0 {stroke: rgba(31,35,41, 0.15)}#COexdeKFaazx .fx0 { stroke-miterlimit: 10; }#COexdeKFaazx .fx0 {stroke-miterlimit: 10}#COexdeKFaazx .fa1 { fill: rgb(187, 191, 196); }#COexdeKFaazx .fa1 {fill: rgb(187, 191, 196)}#COexdeKFaazx .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#COexdeKFaazx .fx1 {font-style: normal}#COexdeKFaazx .fx2 { text-anchor: middle; }#COexdeKFaazx .fx2 {text-anchor: middle}#COexdeKFaazx .fx3 { dominant-baseline: central; }#COexdeKFaazx .fx3 {dominant-baseline: central}#COexdeKFaazx .fx4 { stroke: none; }#COexdeKFaazx .fx4 {stroke: none}#COexdeKFaazx .fc0 { fill: var(--text-caption); }#COexdeKFaazx .fc0 {fill: #646a73}#COexdeKFaazx .fa2 { fill: var(--text-link-disabled); }#COexdeKFaazx .fa2 {fill: rgb(187, 191, 196)}#COexdeKFaazx .fa3 { fill: rgb(225, 234, 255); }#COexdeKFaazx .fa3 {fill: rgb(225, 234, 255)}#COexdeKFaazx .fx5 { font: 700 16px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#COexdeKFaazx .fx5 {font-style: normal}#COexdeKFaazx .fx6 { text-anchor: start; }#COexdeKFaazx .fx6 {text-anchor: start}#COexdeKFaazx .fx7 { dominant-baseline: alphabetic; }#COexdeKFaazx .fx7 {dominant-baseline: alphabetic}#COexdeKFaazx .fc1 { fill: rgb(79, 79, 79); }#COexdeKFaazx .fc1 {fill: rgb(79, 79, 79)}#COexdeKFaazx .fx8 { font: 400 14px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#COexdeKFaazx .fx8 {font-style: normal}#COexdeKFaazx .fb1 { fill: var(--N900-FG, 0.15); }#COexdeKFaazx .fb1 {fill: rgba(31,35,41, 0.15)}#COexdeKFaazx .fb2 { fill: rgb(221, 221, 221); }#COexdeKFaazx .fb2 {fill: rgb(221, 221, 221)}#COexdeKFaazx .fa4 { fill: var(--bg-body); }#COexdeKFaazx .fa4 {fill: #fff}ABC1234组件大脑（LLM）工具（Tools）记忆（Memory）作用类比负责推理、规划、决策执行具体操作（搜索、计算、读写文件等）存储历史对话和中间结果人的大脑人的双手人的记忆

理解了这三个组件，你就理解了 Agent 的本质。

1.3 我们要做什么？

本教程将带你从零构建一个任务助手 Agent，它能够：

•

✅ 接收自然语言任务描述

•

✅ 自主拆解任务步骤

•

✅ 调用工具（计算器、文件读写、网络请求）

•

✅ 根据工具返回结果调整计划

•

✅ 最终输出完整的任务结果

第一阶段：环境准备（15 分钟）

第 1 步：安装依赖

代码块

Markdown

# 创建虚拟环境（强烈推荐，避免依赖冲突）

python -m venv agent-env

source agent-env/bin/activate # Linux/macOS

agent-env\Scripts\activate # Windows

# 安装核心依赖

pip install openai python-dotenv requests colorama

# 验证安装

python -c "import openai; print('OpenAI SDK 安装成功')"

🤖

没有 OpenAI API Key？可以用国内的兼容接口（如 DeepSeek、智谱 GLM），只需修改 base_url 即可，后面会说。

第 2 步：项目结构初始化

代码块

Bash

mkdir my-agent && cd my-agent

# 创建目录结构

mkdir -p src/{tools,memory,core}

mkdir -p tests

mkdir -p logs

# 创建文件

touch src/__init__.py

touch src/tools/__init__.py

touch src/memory/__init__.py

touch src/core/__init__.py

touch .env

touch main.py

最终目录结构如下：

代码块

Bash

第 3 步：配置 API Key

编辑 .env 文件：

代码块

Markdown

# OpenAI 官方

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

OPENAI_BASE_URL=https://api.openai.com/v1

MODEL_NAME=gpt-4o-mini

# 或者使用 DeepSeek（国内更稳定，价格更低）

# OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

# OPENAI_BASE_URL=https://api.deepseek.com/v1

# MODEL_NAME=deepseek-chat

# 或者使用智谱 GLM

# OPENAI_API_KEY=xxxxxxxxxxxxxxxx

# OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4

# MODEL_NAME=glm-4-flash

🤖

推荐新手用 DeepSeek：价格极低（约 OpenAI 的 1/20），API 完全兼容 OpenAI 格式，国内访问稳定。

第二阶段：构建核心组件（50 分钟）

第 4 步：封装 LLM 客户端

新建 src/core/llm_client.py：

代码块

Python

"""

LLM 客户端封装

统一管理大模型调用，支持多种 API 提供商

"""

飞书文档 - 图片

第 5 步：构建工具系统

Agent 的能力来自工具。我们先实现三个最常用的工具。

工具一：计算器 src/tools/calculator.py

代码块

Python

"""

计算器工具

让 Agent 能够执行数学计算，避免大模型的计算幻觉

"""

import math

class CalculatorTool:

"""安全的数学计算工具"""

name = "calculator"

description = (

工具二：文件读写 src/tools/file_tool.py

代码块

Python

"""

文件读写工具

让 Agent 能够读取和写入本地文件

"""

import os

class FileTool:

"""文件操作工具"""

工具三：网络请求 src/tools/web_tool.py

代码块

Python

第 6 步：构建对话记忆

新建 src/memory/conversation.py：

代码块

Python

"""

对话记忆模块

管理 Agent 的上下文历史，支持长度限制和摘要压缩

"""

class ConversationMemory:

"""对话历史管理"""

第三阶段：实现 Agent 核心逻辑（40 分钟）

这是整个教程最关键的部分。

第 7 步：实现 ReAct Agent

新建 src/core/agent.py：

代码块

Python

Thought: [分析当前情况，思考下一步该做什么]

Action: [工具名称]

Action Input: [工具的输入参数]

代码块

Plain Text

当工具返回结果后，你会收到：

Observation: [工具返回的结果]

代码块

Plain Text

Thought: [最终思考，确认任务已完成]

Final Answer: [给用户的最终回答]

代码块

SQL

## 重要规则：

每次只能调用一个工具
如果不需要工具，直接输出 Final Answer
遇到计算问题，必须使用 calculator 工具，不要自己心算
Action 字段只能填写工具名称，不能有其他内容

第四阶段：组装并运行（20 分钟）

第 8 步：创建入口文件

新建 main.py：

代码块

Python

"""

AI Agent 入口文件

"""

from src.core.agent import ReActAgent

def main():

agent = ReActAgent()

第 9 步：运行！

代码块

Plain Text

你会看到类似这样的输出：

代码块

YAML

============================================================

🤖 AI Agent 已启动！输入 'quit' 退出，'reset' 重置对话

============================================================

📝 请输入任务：计算 (123 + 456) * 789 的结果，然后把结果写入 result.txt 文件

============================================================

🤖 任务开始：计算 (123 + 456) * 789 的结果，然后把结果写入 result.txt 文件

============================================================

── 第 1 轮迭代 ──

LLM 输出：

Thought: 用户需要我先计算数学表达式，再把结果写入文件。先用计算器工具计算。

Action: calculator

第五阶段：扩展与优化（自选）

第 10 步：添加更多工具

工具系统是 Agent 能力的上限。你可以轻松扩展更多工具：

代码块

Python

# 示例：添加一个"当前时间"工具

class TimeTool:

name = "get_time"

description = "获取当前的日期和时间。无需输入参数，直接调用即可。"

def run(self, _: str = "") -> str:

from datetime import datetime

now = datetime.now()

return f"当前时间：{now.strftime('%Y年%m月%d日 %H:%M:%S')}"

把新工具注册到 Agent 中：

代码块

Plain Text

# 在 ReActAgent.__init__ 中添加

self.tools["get_time"] = TimeTool()

self.tools["get_weather"] = WeatherTool()

就这么简单，Agent 立刻获得了新能力。

第 11 步：添加流式输出

让 Agent 的思考过程实时显示，体验更好：

代码块

Python

第 12 步：持久化对话历史

让 Agent 在重启后还能记住之前的对话：

代码块

Python

二、常见问题 & 排错指南

Q：运行报错 AuthenticationError？

代码块

Plain Text

Q：Agent 陷入死循环，一直调用同一个工具？

代码块

Plain Text

Q：LLM 输出格式不对，解析总是失败？

代码块

Plain Text

换用更强的模型（如 gpt-4o 替代 gpt-4o-mini），

或者在 system prompt 中加入更多格式示例（few-shot）。

Q：工具调用很慢，怎么优化？

代码块

Plain Text

Q：想用本地模型（Ollama）怎么接入？

代码块

Plain Text

# Ollama 完全兼容 OpenAI API 格式，只需修改 .env：

OPENAI_API_KEY=ollama # 随便填，Ollama 不验证

OPENAI_BASE_URL=http://localhost:11434/v1

MODEL_NAME=qwen2.5:7b # 你本地拉取的模型名

三、完整代码汇总

所有代码已整理到以下结构，可直接克隆使用：

代码块

Plain Text

my-agent/

├── src/

│ ├── core/

│ │ ├── agent.py ✅ ReAct Agent 核心

│ │ └── llm_client.py ✅ LLM 客户端

│ ├── tools/

│ │ ├── calculator.py ✅ 计算器

│ │ ├── file_tool.py ✅ 文件读写

│ │ └── web_tool.py ✅ 网络请求

│ └── memory/

│ └── conversation.py ✅ 对话记忆

├── .env ✅ API 配置

└── main.py ✅ 入口文件

四、总结

恭喜你！完成这个教程后，你已经掌握了：

知识点

掌握程度

AI Agent 的核心概念（LLM + Tools + Memory）

✅

ReAct 范式（Thought → Action → Observation）

✅

如何封装 LLM 调用客户端

✅

如何设计和实现工具系统

✅

如何管理对话上下文记忆

✅

如何解析 LLM 的结构化输出

✅

如何扩展 Agent 能力（添加新工具）

✅

🤖

下一步可以探索的方向：

🔍 RAG（检索增强生成）：给 Agent 接入知识库，让它能回答私有文档的问题

🤝 Multi-Agent：多个 Agent 协作完成复杂任务

🧠 长期记忆：用向量数据库存储历史，让 Agent 真正"记住"你

本文转载：CSDN凤年徐