小白 0 基础 Agent 开发实战 01：先把环境跑起来

关于作者

半旧，FDE，专注垂类 Agent 开发。
做过运动损伤康复、有色金属财报、跨国企业安全月报、小语种新闻自动打标、古文拼音标注、软著申请、模拟演习、智能采购等领域的智能体项目。
阿里云专家博主、CSDN 内容合伙人、腾讯云创作之星，获 VibeFriends 首届黑客松大赛社区热度 TOP 1。
科技向善 OPC 社区创始人之一，倡导：科技向善，创业向实，永续发展。
坐标佛山,希望结识更多朋友，一起交流学习。欢迎联系合作与交流。

这个教程适合谁？

这套教程主要面向：

• 没有 Agent 开发经验的同学；

• 编程基础较少，但愿意动手尝试的同学；

• 希望从“了解概念”走到“真正跑起来”的同学。

你不需要一上来就弄懂所有概念。跟着步骤操作、遇到报错学会搜索和记录，我们一起循序渐进的学习。

系列简介

这是一个面向零基础学习者的 Agent 开发系列。我们会先用通俗的语言讲清 AI 与 Agent 的基本概念，再通过实际操作，带你从环境搭建开始，一步步运行并开发自己的 Agent。

整个系列强调“边学边做”：不要求你提前掌握大量编程知识，先把程序跑起来，再在实践中理解概念。

这是系列第 01 篇，主题是环境准备，内容分为两部分：

1. 前置知识：简单认识 AI 与 Agent、电脑中的文件与路径，以及开发终端；
2. 环境实战：配置 Python、Git、模型 API 和 LangSmith，最后完成环境自检。

第一部分：前置知识

1. 什么是 AI？

参考视频：吴恩达《AI for Everyone》

AI（人工智能）不是某一个软件，而是一大类让电脑表现出“智能”的技术。它可以识别图片、理解文字、预测结果、生成内容，也可以辅助人类做判断。

💡 补充知识：几个常见的 AI 概念

下面这些词经常会出现，现在只需要有一个大概印象：

• 机器学习：不把所有规则都写死，而是让电脑从数据中寻找规律；

• 深度学习：机器学习的一种，使用神经网络处理更复杂的规律；

• 大语言模型（LLM）：通过大量文本学习语言规律，能够理解和生成文字；

• 生成式 AI：可以生成文字、图片、音频、视频或代码的 AI。
  

💡 补充知识：ANI 与 AGI

现在真正被广泛使用的，大多是专用人工智能（ANI）。它可能非常擅长写作、翻译或识图，但不代表它像人一样什么都会。能够像人类一样处理各种任务的通用人工智能（AGI），目前仍是研究目标。

💡 补充知识：AI 幻觉

大模型并不是一个永远正确的知识库。它更像是在根据已有信息，生成“最可能合适”的回答。因此，它可能理解错问题，也可能一本正经地给出错误内容，这通常被称为 AI 幻觉。使用 AI 时，我们仍然需要检查重要结果。

2. 什么是 Agent？

如果说大模型是一个“会思考、会表达的大脑”，那么 Agent（智能体）就是给这个大脑加上目标、工具和行动能力，让它从“会回答”走向“会做事”。

💡 补充知识：Agent 的组成

一个基础 Agent 通常包含：

• 模型：负责理解问题、分析情况和决定下一步；

• 指令与目标：告诉 Agent 要做什么，以及哪些事情不能做；

• 工具：让 Agent 能够搜索网页、读取文件、运行代码或调用其他服务；

• 上下文与记忆：保存当前任务所需的信息和已经完成的步骤；

• 执行循环：观察现状、思考下一步、调用工具、检查结果，直到完成任务。

例如，你让普通聊天 AI“整理一个文件夹”，它可能只会告诉你整理方法；而获得文件工具和操作权限的 Agent，可以先查看文件、制定分类方案、移动文件，再检查是否整理完成。

所以，Agent 并不是一种全新的大模型，而是一套围绕大模型搭建的任务执行系统。它通常按照下面的流程工作：

接收目标 → 制定计划 → 调用工具 → 查看结果 → 调整下一步 → 完成任务

Agent 能做更多事情，也意味着需要更清楚的权限边界。删除文件、发送邮件、执行代码等高风险操作，最好先经过人的确认。

3. 认识你的电脑

参考视频：《认识你的电脑》

开发并不是在做一件完全陌生的事。代码和图片、音乐、Word 文档一样，本质上也是保存在电脑里的文件。

开始开发前，我们先认识四个基础概念：

• 文件：保存具体内容，例如图片、文档和代码；

• 文件夹（目录）：用来分类和存放文件；

• 扩展名：表示文件类型，例如 .png、.docx、.py 和 .md；

• 路径：文件在电脑中的位置，例如 macOS/Linux 的 /Users/name/project，或 Windows 的 C:\Users\name\project。

从根目录开始写出的完整位置叫绝对路径，从当前目录出发的位置叫相对路径。以后让 Agent 读取某个文件时，提供准确的路径，它才能找到正确的内容。

写代码时，我们通常会用 VS Code 等编辑器打开整个项目文件夹，再在里面创建和修改代码文件。可以先记住一句话：项目是一个文件夹，代码是文件，路径是它们的地址。

4. 了解开发终端

参考视频：《终端与 Linux 直觉》

平时我们通过点击、拖动和双击操作电脑，这叫图形界面。终端则是另一种操作方式：输入文字命令，直接告诉电脑要做什么。

终端也常被叫作 命令行、CLI 或 Terminal。macOS/Linux 可以使用 Terminal，Windows 初学者可以使用 PowerShell。

一些常见命令如下：

命令	作用
pwd	查看当前所在路径
ls	查看当前目录中的内容
cd 目录名	进入一个目录
mkdir 目录名	创建目录
touch 文件名	创建文件（macOS/Linux）
cat 文件名	查看文本文件内容
clear	清理终端画面

终端的关键不是死记命令，忘记了可以问ai,用多了也就会自然记住。重点是建立一些基础认知,都可以做什么操作.

下面是几个tips:

执行操作前多用 pwd 和 ls 确认位置，尤其要谨慎使用 rm 等删除命令，因为终端删除通常不会进入回收站。

在项目目录中，还可以输入下面的命令，用 VS Code 打开当前文件夹：

code .

如果出现 command not found，说明还需要在 VS Code 中安装 code 命令，或者暂时通过“文件 → 打开文件夹”进入项目。

第二部分：环境准备实战

前置知识了解完毕，下面正式开始动手配置环境。

❓先抛一个问题

你的电脑离“能跑 Agent”到底还差几步？

今天重点完成什么？

今天需要准备好四样东西：

1. Python 3.11+：运行 Agent 代码；
2. Git：管理代码和学习记录；
3. 模型 API：让程序能够调用大模型；
4. LangSmith：查看 Agent 的调用过程，方便排查问题。
   

第一步：检查 Python

课程要求 Python 3.11 或更高版本。先检查版本：

python --version

如果命令不存在，可以再试：

python3 --version

接着创建并激活项目环境：

python -m venv .venv

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

终端前面出现 (.venv) 后，安装基础依赖：

python -m pip install -U pip
pip install deepagents langchain-openai langsmith

💡 补充知识：虚拟环境、pip 与依赖

Python 可以理解为运行 Agent 代码的“发动机”,用它可以把我们的python代码跑起来。虚拟环境则像当前项目的独立工具箱，可以避免不同项目需要的python软件版本互相冲突。.venv 是这个工具箱常用的文件夹名称。

pip 是 Python 的软件包安装工具；软件包是别人已经写好的可复用代码；项目运行需要的软件包，也叫作项目的依赖。

第二步：检查 Git

先检查 Git 是否可用：

git --version

第一次使用 Git，可以设置提交者信息：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

然后在练习目录执行：

git init
git status

💡 补充知识：Git 与仓库

Git 是代码的版本管理工具，可以把它理解成游戏里的“存档系统”。它会记录代码发生了哪些变化，方便我们查看历史或恢复到之前的版本。

git init 会把当前文件夹变成一个由 Git 管理的仓库，git status 用来查看仓库目前有哪些变化。

第三步：配置模型 API

本篇以 DeepSeek-V4-Flash 为例。它的 API 兼容 OpenAI 格式，可以直接配合后面使用的 langchain-openai。

1. 创建 API Key

打开 DeepSeek 开放平台，注册并登录账号，然后进入 API Keys 页面 创建密钥。

2. 配置环境变量

# macOS / Linux
export DEEPSEEK_API_KEY="你的 DeepSeek API Key"
export MODEL_NAME="deepseek-v4-flash"

# Windows PowerShell
$env:DEEPSEEK_API_KEY="你的 DeepSeek API Key"
$env:MODEL_NAME="deepseek-v4-flash"

检查环境变量是否已经设置：

python -c "import os; print('API Key 已配置' if os.getenv('DEEPSEEK_API_KEY') else 'API Key 未配置')"

出现“API Key 已配置”后即可继续。真正的模型连通测试会放在后面的“环境自检”中。

API Key 就像密码，不要公开截图，也不要写进代码或提交到 Git 仓库。上述设置通常只对当前终端窗口有效，关闭后可能需要重新配置。API 按实际用量计费，使用前请查看 DeepSeek 模型与价格。

💡 补充知识：API、API Key 与环境变量

API 可以理解为程序访问模型服务的“窗口”，代码通过它把问题交给大模型，再拿回结果。API Key 像访问窗口的个人钥匙，用于识别身份和统计用量。

环境变量是保存在操作系统中的配置信息。程序可以读取它，这样就不必把密钥直接写进代码。

根据 DeepSeek 官方文档，本例使用的关键参数是：

参数	值
API 地址	https://api.deepseek.com
模型名称	deepseek-v4-flash
API Key 环境变量	DEEPSEEK_API_KEY

deepseek-v4-flash 是稳定的调用名称，背后的具体模型版本可能由官方继续更新。DeepSeek-V4-Flash 支持思考与非思考模式；本篇的连通测试会关闭思考模式，以减少等待时间和 Token 消耗。

💡 补充知识：常见模型厂商与平台

厂商或平台	常见模型	简单特点	官方文档
DeepSeek（深度求索）	DeepSeek V4	推理、代码与 Agent 场景，API 兼容 OpenAI/Anthropic 格式	API 文档
OpenAI	GPT 系列	通用能力、工具调用和多模态生态成熟	开发文档
Anthropic	Claude 系列	长文本、代码和复杂任务处理	API 文档
Google	Gemini 系列	多模态能力及 Google 生态集成	Gemini API
阿里云百炼	Qwen（通义千问）系列	中文与开源模型生态丰富，国内访问方便	模型服务文档
智谱 AI	GLM 系列	中文、工具调用与智能体应用	开放平台文档
Moonshot AI	Kimi 系列	中文和长上下文应用	Kimi API 文档
SiliconFlow（硅基流动）	多种开源模型	它是模型服务平台，可通过统一 API 使用多家开源模型	平台文档

模型没有绝对的“最好”。入门时主要考虑是否支持工具调用、价格、访问是否稳定(如没有稳定网络环境,可用国产模型)，以及 API 文档是否清楚。不同平台的模型名称和价格会变化，请以官方页面为准。

第四步：配置 LangSmith

当 Agent 的行为不符合预期时，只看最终回答通常很难找到原因。LangSmith 是 LangChain 提供的可观测与调试平台，可以把 Agent 的模型调用、工具调用和执行步骤记录下来。

1. 创建 LangSmith API Key

打开 LangSmith 注册并登录，在 Settings → API Keys 中创建密钥。详细步骤可查看官方文档。

2. 配置环境变量

# macOS / Linux
export LANGSMITH_TRACING="true"
export LANGSMITH_API_KEY="你的 LangSmith API Key"
export LANGSMITH_PROJECT="agent-zero-to-one"

# Windows PowerShell
$env:LANGSMITH_TRACING="true"
$env:LANGSMITH_API_KEY="你的 LangSmith API Key"
$env:LANGSMITH_PROJECT="agent-zero-to-one"

检查配置是否存在：

python -c "import os; print('LangSmith 已配置' if os.getenv('LANGSMITH_API_KEY') else 'LangSmith 未配置')"

如果 API Key 同时关联多个工作区，还需要按照 LangSmith 页面提示设置 LANGSMITH_WORKSPACE_ID。

3. 指定 Trace 的保存位置

LangSmith 需要把运行记录分类保存。你可以把它理解成创建一个文件夹：文件夹里放的是 Trace，LangSmith 把这个“文件夹”称为 Project。

配置中的这一行：

export LANGSMITH_PROJECT="agent-zero-to-one"

意思就是：把这次课程产生的 Trace 都放进名为 agent-zero-to-one 的分类中。

**agent-zero-to-one**不需要提前去网页创建。第一条 Trace 上传成功后，LangSmith 会自动生成这个分类；如果没有设置名称，记录会进入 default。

登录 LangSmith 后，找到 agent-zero-to-one，就能查看后面运行 check_model.py 产生的记录。如果没有看到，请确认登录的是创建 API Key 时使用的同一账号和工作区，然后刷新页面。

在 LangChain、LangGraph 或 Deep Agents 已接入追踪的情况下，设置环境变量后通常不需要修改业务代码，运行记录就会上传到这个分类中。

Trace 中可能包含提示词、模型回答和工具参数，不要把密码、API Key 或其他敏感数据放进测试内容。

💡 补充知识：什么是可观测性与 Trace？

可观测性就是让我们能够看清程序运行时发生了什么。Agent 出错时，LangSmith 就像一台“行车记录仪”。

一次完整任务的运行记录叫作 Trace（追踪记录）。它通常由多个步骤组成，每个模型调用、工具调用或子 Agent 任务都可以成为其中的一个节点。

在 Trace 面板中，可以查看：

• 每次模型调用的输入与输出；

• 工具调用的参数和返回结果；

• 子 Agent 的执行过程；

• 每一步的耗时，以及集成能够提供时的 Token 用量；

• Agent 记录到 Trace 中的文件读取、写入等操作。

通俗地说，它能帮助我们理解“Agent 为什么会走到这一步”。不过，LangSmith 展示的是实际记录下来的调用和执行过程，并不是读取模型没有输出的隐藏思维。虚拟文件系统的变化也需要 Agent 将相关操作记录到 Trace 后才能看到。

环境自检

找到这里，就找到开头问题的答案了：通常需要完成 5 步自检。

1. Python 版本正常

python --version

版本应为 3.11 或更高。

2. Git 可以使用

git --version
git status

3. 依赖可以导入

python -c "import deepagents, langsmith; print('依赖检查通过')"

4. 模型 API 可以调用

新建 check_model.py：

import os

from langchain_openai import ChatOpenAI
from langchain_core.tracers.langchain import wait_for_all_tracers

model = ChatOpenAI(
    model=os.environ.get("MODEL_NAME", "deepseek-v4-flash"),
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
    extra_body={"thinking": {"type": "disabled"}},
)

try:
    result = model.invoke("只回复：环境自检成功")
    print(result.content)
finally:
    wait_for_all_tracers()

运行：

python check_model.py

终端能返回内容，说明 Python、依赖和模型 API 已经基本打通。

5. LangSmith 能看到 Trace

打开 LangSmith，进入 agent-zero-to-one 项目。如果能看到刚才 check_model.py 产生的运行记录，说明追踪配置成功。

最终清单：

• Python 版本符合要求

• Git 可以正常使用

• 项目依赖安装成功

• 模型 API 调用成功

• LangSmith 能看到 Trace

五项全部勾选，恭喜你：电脑已经具备运行 Agent 的基础条件。

学习资料

• 图文教程：Deep Agents 实战——从零构建生产级 AI Agent 的完整指南

• 视频教程：B 站《Deep Agents 实战》合集

建议先看图文步骤，再用视频补充理解。不要只看不做，环境配置一定要亲手跑一遍。

今日小结

今天没有急着写 Agent，而是先打好了地基：Python 负责运行代码，Git 负责管理代码，模型 API 提供智能能力，LangSmith 帮助我们看清运行过程。

下一步，我们就可以在这套环境上，真正运行第一个 Agent 了。