AI Agent 新手入门指南｜附源码

过去一年，“AI Agent（智能体）”从概念迅速走向实践。相比只能回答问题的普通大模型应用，AI Agent 更像一个具备“目标理解、任务规划、工具调用、记忆管理、结果反思”能力的自动化助手。它不仅能聊天，还能根据目标主动拆解步骤、调用搜索、数据库、代码执行、文件读写等工具，最终完成一项复杂任务。

本文面向 AI Agent 新手，尽量用通俗语言讲清楚：什么是 AI Agent、它和普通 ChatGPT 应用有什么区别、核心组成是什么、如何从零写一个简单 Agent，并附带可运行源码示例。

一、什么是 AI Agent？

简单来说，AI Agent 是一个能够围绕目标自主行动的软件系统。

普通大模型应用通常是这样的：

用户提问 → 大模型回答 → 结束

而 AI Agent 更像这样：

用户提出目标 → Agent 理解目标 → 制定计划 → 选择工具 → 执行任务 → 观察结果 → 调整计划 → 得出最终答案

例如，你对一个普通聊天机器人说：

帮我分析一下某个网站最近的产品更新。

它可能只能根据已有知识回答，或者告诉你“我无法访问网页”。

但如果是一个配置了工具的 AI Agent，它可以：

1. 理解你的目标；
2. 调用网页搜索工具；
3. 抓取目标网站内容；
4. 提取产品更新信息；
5. 总结变化；
6. 给出分析结论；
7. 必要时生成报告或表格。

这就是 AI Agent 的核心价值：让大模型从“回答问题”升级为“执行任务”。

二、AI Agent 和普通大模型应用的区别

很多初学者会把 AI Agent 和 ChatGPT 类应用混为一谈。它们确实都依赖大语言模型，但设计思想不同。

举个例子：

你输入：

帮我写一份竞品分析报告。

普通大模型可能直接生成一篇看似合理但缺乏实时数据的报告。

AI Agent 则可以按照下面的流程执行：

1. 确定竞品名单；
2. 搜索竞品官网、新闻、社交媒体；
3. 提取价格、功能、定位、用户反馈；
4. 整理成结构化表格；
5. 对比优劣势；
6. 生成最终报告。

所以，AI Agent 的重点不只是“会说”，而是“会做”。

三、AI Agent 的核心组成

一个典型 AI Agent 通常包括以下几个模块。

1. 大语言模型：Agent 的大脑

大语言模型是 Agent 的决策中心，负责理解任务、规划步骤、判断是否需要调用工具，以及生成最终结果。

常见模型包括：

• GPT 系列；
• Claude 系列；
• Gemini 系列；
• DeepSeek；
• Qwen；
• Llama；
• GLM 等。

在 Agent 系统中，模型并不是单纯负责输出答案，而是负责判断：

• 当前任务要做什么？
• 是否需要工具？
• 该调用哪个工具？
• 工具返回结果是否满足需求？
• 下一步应该怎么做？

2. Prompt：Agent 的行为规则

Prompt 不只是给模型的一句话提示，而是 Agent 的“系统说明书”。

一个好的 Agent Prompt 通常会说明：

• 你是谁；
• 你的目标是什么；
• 你有哪些工具；
• 什么时候使用工具；
• 输出格式是什么；
• 遇到不确定信息应该怎么处理；
• 是否允许编造；
• 任务完成标准是什么。

例如：

你是一个任务型 AI Agent。
你的职责是根据用户目标制定计划，并在需要时调用工具。
如果缺少信息，请主动询问用户。
如果工具返回结果不足，请继续搜索或说明限制。
最终回答必须结构清晰、结论明确。

Prompt 决定了 Agent 的工作风格和边界。对新手来说，很多 Agent “看起来不聪明”，其实不是模型不行，而是 Prompt 写得太随意。

3. Tools：工具调用能力

工具是 AI Agent 能够“行动”的关键。

常见工具包括：

• 搜索工具；
• 网页抓取工具；
• 数据库查询；
• 文件读写；
• 代码执行器；
• 邮件发送；
• 日历管理；
• API 调用；
• Excel/CSV 分析；
• 图片生成；
• 向量数据库检索。

没有工具的 Agent，往往只能在语言层面推理；有了工具，它才能真正接触外部世界。

例如，一个天气查询 Agent 可以调用天气 API；一个客服 Agent 可以查询订单数据库；一个研发 Agent 可以读取代码仓库并生成修改建议。

4. Memory：记忆系统

记忆系统让 Agent 能够保存上下文和用户偏好。

记忆一般分为两类：

短期记忆

短期记忆通常指当前对话上下文，例如用户刚才说过什么、工具调用结果是什么。

长期记忆

长期记忆可以跨会话保存信息，例如：

• 用户喜欢 Markdown 格式；
• 用户所在城市是上海；
• 用户常用 Python；
• 某项目的技术栈是 React + FastAPI；
• 某客户历史购买记录。

长期记忆通常会结合数据库、向量数据库或文件系统来实现。

5. Planning：任务规划

Planning 是 AI Agent 的重要能力。面对复杂任务，Agent 需要将目标拆成若干步骤。

例如用户要求：

帮我设计一个线上课程销售页面。

Agent 可以拆解为：

1. 明确目标用户；
2. 分析课程卖点；
3. 设计页面结构；
4. 撰写首屏文案；
5. 设计价格模块；
6. 设计 FAQ；
7. 输出完整页面文案。

更高级的 Agent 还会根据执行结果动态调整计划，而不是一次性固定路线。

6. Reflection：反思与修正

Reflection 指 Agent 对自己的结果进行检查和修正。

例如它生成一段代码后，可以自检：

• 是否符合用户需求？
• 是否有语法错误？
• 是否缺少异常处理？
• 是否有安全风险？
• 输出格式是否正确？

反思机制可以显著提升 Agent 的稳定性，尤其适用于代码生成、数据分析、长文写作等复杂任务。

四、AI Agent 的常见工作流程

一个基础 AI Agent 可以采用如下循环：

用户目标
  ↓
理解任务
  ↓
制定计划
  ↓
判断是否需要工具
  ↓
调用工具
  ↓
观察工具结果
  ↓
继续推理或调整计划
  ↓
输出最终答案

在很多开源框架中，这种模式被称为：

• ReAct：Reasoning + Acting；
• Plan-and-Execute；
• Tool Calling Agent；
• Function Calling Agent。

其中 ReAct 是非常经典的 Agent 模式。它将“思考”和“行动”结合起来，让模型在执行过程中不断推理和调用工具。

五、适合新手的 AI Agent 开发路线

如果你刚开始学习 AI Agent，不建议一上来就研究复杂多 Agent 系统。可以按照以下路线逐步学习。

第一步：学会调用大模型 API

你需要先掌握如何向模型发送消息，并获取回复。

重点包括：

• API Key 配置；
• 模型选择；
• system/user/assistant 消息结构；
• temperature 参数；
• max_tokens 参数；
• 流式输出；
• 错误处理。

第二步：学会 Prompt 设计

你需要理解不同 Prompt 对输出结果的影响。

推荐练习：

• 写一个文章生成助手；
• 写一个翻译助手；
• 写一个代码解释助手；
• 写一个面试题生成助手；
• 写一个 SQL 生成助手。

第三步：接入工具

这是从普通应用进阶到 Agent 的关键一步。

你可以先做一些简单工具：

• 计算器；
• 当前时间查询；
• 本地文件读取；
• 天气查询；
• 搜索模拟器；
• 数据库查询模拟器。

先不要追求复杂，关键是理解：模型如何决定调用工具，以及工具结果如何返回给模型继续推理。

第四步：加入任务循环

让 Agent 不是只调用一次工具，而是可以多轮执行。

例如：

1. 模型判断要调用计算器；
2. 工具返回计算结果；
3. 模型继续判断是否还需要别的工具；
4. 最终输出答案。

这就是 Agent 的基本雏形。

第五步：加入记忆和日志

当 Agent 变复杂后，日志非常重要。

你需要记录：

• 用户输入；
• 模型输出；
• 工具调用参数；
• 工具返回结果；
• 每一步耗时；
• 错误信息。

没有日志的 Agent 很难调试，因为你不知道它为什么做出某个决策。

六、从零实现一个简单 AI Agent

下面我们用 Python 实现一个非常简单的 Agent。

它具备以下能力：

1. 接收用户问题；
2. 判断是否需要调用工具；
3. 支持计算器工具；
4. 支持当前时间工具；
5. 将工具结果返回给模型；
6. 输出最终答案。

为了方便演示，下面示例使用 OpenAI 风格的接口。如果你使用的是兼容 OpenAI API 的国产模型服务，也可以替换 base_url 和 model。

七、项目结构

建议创建如下目录：

simple-ai-agent/
├── main.py
├── tools.py
├── agent.py
├── requirements.txt
└── .env

八、安装依赖

requirements.txt 内容如下：

openai>=1.40.0
python-dotenv>=1.0.1

安装依赖：

pip install -r requirements.txt

九、配置环境变量

创建 .env 文件：

OPENAI_API_KEY=你的_API_Key
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL_NAME=gpt-4o-mini

如果你使用其他兼容 OpenAI 格式的模型服务，可以修改：

OPENAI_BASE_URL=https://你的服务地址/v1
MODEL_NAME=你的模型名称

十、工具代码：tools.py

# tools.py
from datetime import datetime
import ast
import operator


def get_current_time(_: dict | None = None) -> str:
    """
    获取当前时间。
    """
    now = datetime.now()
    return now.strftime("%Y-%m-%d %H:%M:%S")


_ALLOWED_OPERATORS = {
    ast.Add: operator.add,
    ast.Sub: operator.sub,
    ast.Mult: operator.mul,
    ast.Div: operator.truediv,
    ast.Pow: operator.pow,
    ast.USub: operator.neg,
}


def _eval_node(node):
    """
    安全计算数学表达式，只允许基础运算。
    """
    if isinstance(node, ast.Num):
        return node.n

    if isinstance(node, ast.BinOp):
        left = _eval_node(node.left)
        right = _eval_node(node.right)
        op_type = type(node.op)

        if op_type not in _ALLOWED_OPERATORS:
            raise ValueError("不支持的运算符")

        return _ALLOWED_OPERATORS[op_type](left, right)

    if isinstance(node, ast.UnaryOp):
        operand = _eval_node(node.operand)
        op_type = type(node.op)

        if op_type not in _ALLOWED_OPERATORS:
            raise ValueError("不支持的一元运算符")

        return _ALLOWED_OPERATORS[op_type](operand)

    raise ValueError("表达式不安全或不支持")


def calculator(args: dict) -> str:
    """
    安全计算数学表达式。
    参数示例：
    {
        "expression": "3 * (5 + 2)"
    }
    """
    expression = args.get("expression", "")

    if not expression:
        return "错误：缺少 expression 参数"

    try:
        tree = ast.parse(expression, mode="eval")
        result = _eval_node(tree.body)
        return str(result)
    except Exception as e:
        return f"计算失败：{e}"


TOOLS = {
    "get_current_time": get_current_time,
    "calculator": calculator,
}


TOOL_SCHEMAS = [
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "获取当前系统时间。当用户询问当前日期、时间、今天几号等信息时使用。",
            "parameters": {
                "type": "object",
                "properties": {},
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "calculator",
            "description": "用于计算数学表达式，例如加减乘除、括号运算、幂运算等。",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {
                        "type": "string",
                        "description": "需要计算的数学表达式，例如：3 * (5 + 2)",
                    }
                },
                "required": ["expression"],
            },
        },
    },
]

十一、Agent 代码：agent.py

# agent.py
import json
from openai import OpenAI

from tools import TOOLS, TOOL_SCHEMAS


class SimpleAgent:
    def __init__(self, api_key: str, base_url: str, model: str):
        self.client = OpenAI(
            api_key=api_key,
            base_url=base_url,
        )
        self.model = model
        self.messages = [
            {
                "role": "system",
                "content": (
                    "你是一个简单但可靠的 AI Agent。"
                    "你可以根据用户问题决定是否调用工具。"
                    "如果需要计算，请调用 calculator 工具。"
                    "如果需要获取当前时间，请调用 get_current_time 工具。"
                    "不要编造工具结果。"
                    "最终请用简洁、清晰的中文回答用户。"
                ),
            }
        ]

    def chat(self, user_input: str) -> str:
        self.messages.append(
            {
                "role": "user",
                "content": user_input,
            }
        )

        while True:
            response = self.client.chat.completions.create(
                model=self.model,
                messages=self.messages,
                tools=TOOL_SCHEMAS,
                tool_choice="auto",
            )

            message = response.choices[0].message
            self.messages.append(message)

            if not message.tool_calls:
                return message.content

            for tool_call in message.tool_calls:
                tool_name = tool_call.function.name
                raw_args = tool_call.function.arguments or "{}"

                try:
                    args = json.loads(raw_args)
                except json.JSONDecodeError:
                    args = {}

                if tool_name not in TOOLS:
                    tool_result = f"错误：未知工具 {tool_name}"
                else:
                    tool_result = TOOLS[tool_name](args)

                self.messages.append(
                    {
                        "role": "tool",
                        "tool_call_id": tool_call.id,
                        "name": tool_name,
                        "content": tool_result,
                    }
                )

十二、入口代码：main.py

# main.py
import os
from dotenv import load_dotenv

from agent import SimpleAgent


def main():
    load_dotenv()

    api_key = os.getenv("OPENAI_API_KEY")
    base_url = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
    model = os.getenv("MODEL_NAME", "gpt-4o-mini")

    if not api_key:
        raise RuntimeError("请先在 .env 文件中配置 OPENAI_API_KEY")

    agent = SimpleAgent(
        api_key=api_key,
        base_url=base_url,
        model=model,
    )

    print("Simple AI Agent 已启动，输入 exit 退出。")
    print("-" * 40)

    while True:
        user_input = input("你：").strip()

        if user_input.lower() in {"exit", "quit"}:
            print("Agent：再见！")
            break

        if not user_input:
            continue

        try:
            answer = agent.chat(user_input)
            print(f"Agent：{answer}")
        except Exception as e:
            print(f"Agent 运行出错：{e}")


if __name__ == "__main__":
    main()

十三、运行项目

在终端中执行：

python main.py

你可以测试以下问题：

现在几点了？

Agent 会自动调用 get_current_time 工具。

帮我计算 3 * (5 + 2) 的结果

Agent 会自动调用 calculator 工具。

如果我有 120 元，每天花 7.5 元，可以用多少天？

Agent 会调用计算器，并返回解释。

十四、这段源码实现了什么？

这份代码虽然简单，但已经具备 AI Agent 的基础结构。

1. 模型决策

Agent 并不是在代码里用 if user_input contains 时间 这种方式死板判断，而是把工具描述交给模型，让模型自己判断是否调用工具。

这就是工具调用 Agent 的关键思想。

2. 工具执行

当模型决定调用工具时，它会返回类似下面的信息：

{
  "name": "calculator",
  "arguments": {
    "expression": "3 * (5 + 2)"
  }
}

程序收到后，会在 TOOLS 字典中找到对应函数，然后执行。

3. 工具结果回传

工具执行后，结果不会直接返回给用户，而是作为一条 tool 消息再次发送给模型。

这样模型可以基于工具结果组织自然语言答案。

例如计算器返回：

21

模型最终可能回答：

3 * (5 + 2) = 21。

这一步很重要，因为工具只负责“做事”，模型负责“解释”。

十五、如何继续扩展这个 Agent？

上面的 Agent 是一个最小可用版本。你可以从以下方向扩展。

1. 添加搜索工具

可以接入搜索 API，例如 SerpAPI、Bing Search API，或者自建搜索服务。

工具定义示例：

def web_search(args: dict) -> str:
    query = args.get("query", "")
    # 调用搜索接口
    return "搜索结果..."

适合场景：

• 新闻查询；
• 竞品分析；
• 市场调研；
• 热点追踪；
• 资料整理。

2. 添加文件读写工具

让 Agent 能读取和生成文件，例如 Markdown、CSV、JSON。

def write_file(args: dict) -> str:
    filename = args.get("filename")
    content = args.get("content", "")

    with open(filename, "w", encoding="utf-8") as f:
        f.write(content)

    return f"文件已写入：{filename}"

注意：文件工具一定要限制目录，避免 Agent 误删或覆盖重要文件。

3. 添加数据库查询工具

如果你正在做企业应用，数据库工具非常实用。

例如客服 Agent 可以查询：

• 订单状态；
• 用户信息；
• 退款记录；
• 库存信息；
• 发票信息。

但数据库工具要特别注意权限控制，避免模型生成危险 SQL。

建议：

• 只允许只读查询；
• 使用白名单表；
• 限制返回条数；
• 记录所有查询日志；
• 敏感字段脱敏。

4. 加入长期记忆

你可以把用户偏好保存到数据库或向量库中。

例如：

用户偏好：
- 喜欢中文回答；
- 喜欢 Markdown 格式；
- 关注 AI、Python、自动化；
- 输出内容希望结构化。

每次会话开始时，将相关记忆注入 system prompt 或上下文中。

5. 加入任务计划模块

可以让 Agent 先输出计划，再执行。

例如：

任务：生成一份竞品分析报告

计划：
1. 搜索竞品官网信息；
2. 提取功能列表；
3. 对比价格；
4. 汇总用户评价；
5. 输出报告。

这种方式适合复杂任务，可以减少 Agent 盲目执行。

十六、开发 AI Agent 时的常见问题

问题 1：Agent 总是乱调用工具怎么办？

可能原因：

• 工具描述不清楚；
• Prompt 没有说明调用条件；
• 工具数量太多；
• 工具参数设计复杂；
• 模型能力不足。

解决方法：

1. 优化工具描述；
2. 明确什么时候使用工具；
3. 减少工具数量；
4. 给参数添加清晰说明；
5. 在 system prompt 中强调“必要时才调用工具”。

问题 2：Agent 编造工具结果怎么办？

要在 Prompt 中明确：

不要编造工具结果。
如果工具未返回信息，请说明无法确认。

同时，在程序层面要确保工具调用结果确实被回传给模型。

问题 3：Agent 陷入循环怎么办？

例如它不断搜索、不断调用工具，却不输出最终答案。

解决方法：

• 设置最大循环次数；
• 设置最大工具调用次数；
• 要求模型在满足条件后输出最终答案；
• 添加反思判断；
• 记录日志分析问题。

你可以在代码中加入限制：

max_steps = 5
step = 0

while step < max_steps:
    step += 1
    ...

超过次数后强制返回总结。

问题 4：工具权限如何控制？

Agent 能调用工具，也意味着它可能造成风险。

例如：

• 删除文件；
• 发送错误邮件；
• 执行危险代码；
• 查询敏感数据；
• 调用付费 API 产生费用。

建议所有高风险操作都加入确认机制：

在执行删除、发送、支付、修改数据库等操作前，必须先询问用户确认。

程序层面也要做权限限制，而不能只依赖 Prompt。

十七、AI Agent 的典型应用场景

1. 个人效率助手

可以帮用户：

• 安排日程；
• 总结邮件；
• 生成待办清单；
• 整理会议纪要；
• 写周报；
• 查询资料。

2. 数据分析助手

可以接入数据库、Python 执行器、BI 系统，实现：

• 自动查询数据；
• 生成图表；
• 分析趋势；
• 输出结论；
• 生成日报和月报。

3. 编程助手

不仅能回答代码问题，还可以：

• 阅读项目文件；
• 定位 bug；
• 生成测试用例；
• 修改代码；
• 执行命令；
• 总结提交记录。

4. 智能客服

客服 Agent 可以接入订单、物流、售后系统，完成：

• 查询订单；
• 查询物流；
• 判断退款条件；
• 推荐解决方案；
• 自动生成工单。

5. 内容创作助手

内容型 Agent 可以：

• 搜索资料；
• 生成选题；
• 制定大纲；
• 撰写文章；
• 优化标题；
• 生成配图提示词；
• 发布到平台。

十八、AI Agent 开发的最佳实践

1. 从小工具开始

不要一开始就做复杂系统。先做一个只支持 2 到 3 个工具的小 Agent，验证流程跑通后再扩展。

2. 工具要清晰、稳定、可控

工具函数最好满足：

• 输入参数明确；
• 输出结构稳定；
• 异常处理完善；
• 权限边界清楚；
• 有日志记录。

3. 给 Agent 设置边界

Agent 不是越自由越好。越自由，越容易出错。

你应该明确：

• 哪些事可以做；
• 哪些事不能做；
• 哪些操作必须用户确认；
• 哪些结果需要标注不确定性。

4. 保留人类审批

在生产环境中，涉及重要操作时，一定要保留 human-in-the-loop。

例如：

• 发送邮件前确认；
• 删除文件前确认；
• 提交代码前确认；
• 修改订单前确认；
• 支付或退款前确认。

5. 做好日志和监控

生产级 Agent 必须记录执行过程，否则出了问题无法排查。

建议记录：

• 用户请求；
• 模型响应；
• 工具调用；
• 工具结果；
• token 消耗；
• 响应时间；
• 错误信息。

十九、总结

AI Agent 的本质，是让大语言模型不再只是“生成答案”，而是可以围绕目标进行规划、执行和反馈。

对于新手来说，可以先抓住五个关键词：

1. LLM：负责理解和决策；
2. Prompt：定义行为规则；
3. Tools：赋予行动能力；
4. Memory：保存上下文和偏好；
5. Loop：让 Agent 多步执行任务。

本文提供的源码虽然简单，但已经展示了 Agent 的核心机制：模型根据工具描述决定是否调用工具，程序执行工具，再把结果返回给模型生成最终答案。

如果你想继续深入，可以在此基础上加入搜索、文件读写、数据库查询、长期记忆、任务规划和审批机制。只要把这些模块逐步组合起来，你就能构建出真正可用的 AI Agent 应用。

AI Agent 的学习曲线并不低，但入门并不难。最重要的是先动手写一个最小可用版本，然后不断迭代。等你真正跑通一次“模型决策 → 工具调用 → 结果反馈 → 最终回答”的流程，就会发现 Agent 并不是遥不可及的黑科技，而是一种可以被工程化实现的应用架构。