初级 AI Agent 工程师

一、从开篇说起

开篇里我讲过一句话：

AI Agent 工程师现在是一个刚刚被需要、但还没被体系化的岗位。 原生开发者是最适合转过去的一批人，但没人告诉你怎么转。

也立下过一个参照 Android 工程师的进阶模型：

档位	对应 Android	代表能力
初级	能写页面、会调 SDK、懂四大组件	会接 LLM、会写 Prompt、能做基础 RAG、能搭 Demo 级 Agent
中级	会架构、性能优化、组件化	多轮上下文、流式、Tool Use、服务化、检索优化
高级	Framework、SDK、跨端架构、主导项目	Agent 架构、工作流编排、评测体系、成本治理、AI Native 产品落地

这一篇我们正式开始第一档：初级 AI Agent 工程师

本章结束时你应该做到三件事：

1. 能回答"初级 AI Agent 工程师到底意味着什么、过关标准在哪"
2. 能看懂一份真实 AI 应用开发 JD，知道哪些是初级要会、哪些是中级预告
3. 能交付一个最小 RAG Agent Demo（跑得起来、讲得清楚）

配套的开源代码就在这个项目里：

配套的开源代码就在这个项目里：

• main_beginner.py：第一步 ------ 最小 LLM 问答（约 50 行）

• main_rag.py：第二步 ------ 最小 RAG Agent Demo（本章正式交付物）

二、初级 AI Agent 工程师在真实公司里做什么（JD 拆解）

先把结论放在前面：

初级 AI Agent 工程师不是"会写 Prompt 的人"，是"能把 AI 接进已有业务系统、跑出第一个上线版本的人"。

这一节不讲概念，只讲一件事------翻招聘网站，看真岗位真在要什么人。

下面三份 JD 都来自 2026 年 Boss 直聘深圳区公开岗位，已经去除公司名、HR 信息。

1. 三份真实初级 JD 的画像

样本	岗位	薪资	经验 / 学历	方向
JD-①	AI 应用开发工程师（大厂 T 公司）	未披露	1 年+ / 本科	企业经营系统 AI 化（合同、测算、招投标、文档等）
JD-②	AI 应用开发工程师（某存储芯片公司）	22--35K × 13 薪	1--3 年 / 本科	内部研发效能 AI（代码生成 / 代码审查 / 自动化测试 / 文档生成）
JD-③	AI 应用开发工程师（某智能硬件公司）	15--25K × 14 薪	1--3 年 / 本科	AI 服务架构 + LLM/RAG 模块 + Agent 编排

三份 JD 覆盖了初级岗最典型的三个方向：

• 企业内部业务系统 AI 化 → 大厂最常见的"AI 降本增效"类岗位
• 研发效能 AI → 近一年增长最快的新赛道，把 AI 塞进工程师自己的工具链
• 通用 AI 应用工程 → 创业公司 / 中小厂的"AI 功能化"岗位

注意 ：三份 JD 里没有一个是"纯调 API 糊 Demo"的工作。即便是 1 年+ 的最低门槛岗位，也全部要求"实际的 AI Agent 或 RAG 项目落地经验"。

2. 关键词频次：初级岗真正关心什么

（把三份 JD 的任职要求喂进一个关键词表，频次越高说明市场越在乎。）

关键词	JD-①	JD-②	JD-③	命中数
业务场景落地 / 工程化	✅	✅	✅	3
跨团队协作（算法/硬件/产品）	✅	✅	✅	3
AI Agent	✅	✅	✅	3
RAG / 知识库	✅	✅	✅	3
提示词工程	✅	✅		2
MCP / Function Call / Tool			✅	1
长/短期记忆			✅	1
Python（主流语言任一）		✅	✅	2
问题拆解 / 方案设计		✅	✅	2
有落地经验而非理论学习		✅	✅	2

三条从数据里读出来的结论

结论 1：初级岗 3/3 命中"业务场景落地"和"跨团队协作"。

这不是算法岗口径，是产品工程岗口径。恰好是你原生开发者最熟的那块。

结论 2：Agent / RAG 已是初级门槛，不是加分项。

三份 JD 全都提到 Agent 和 RAG。也就是说， "只会调 API"这一档的岗位，已经不在初级招聘池里了 。好消息是------你做完本章的 main_rag.py，这两个关键词你都能打勾。

结论 3：市场已经把"中级技能"下压到初级门槛。

注意 JD-③ 是 1--3 年 的岗位，但它的要求里赫然写着 MCP、Agent 架构设计、RAG 知识库构建与检索、长/短期记忆------这些在一年前是典型的中级词。市场节奏比体系课快得多。

3. 三段原文金句（以下为打码后的 JD 原文直引）

① 大厂视角：初级的真实任务

"负责内部智能化运营工具的建设与优化，结合 AI 等技术持续解决业务场景痛点，极致提升经营效率。"

------JD-① 岗位职责第 3 条

解读：大厂的初级 AI 岗通常不是做"面向用户的 AI 产品"，而是做"面向内部业务/同事的 AI 工具" 。这类岗位数据闭环短、试错成本低、更容易出成绩，是原生转型性价比最高的切入口。

② 最温柔的那句 JD：你不用全会，有一类就够

"具备 AI 项目落地经验，而非仅理论学习，做过 API 调用、提示词工程、RAG、模型微调、Agent 等至少一类。"

------JD-② 核心任职要求第 3 条

解读： "至少一类" 这四个字，就是初级岗给原生开发者留的门。它没要求你全栈通吃，只要求你有一样做过、能讲清楚、能复现。本章你要做的 RAG Demo，就是最容易讲清楚的那一类。

③ 被市场提前"中级化"的初级岗

"熟悉 AI 应用开发的核心技术要点，如 MCP、Agent 架构设计、RAG 知识库构建与检索、长/短期记忆等，并能灵活运用。"

------JD-③ 任职资格第 2 条（注意这是 1--3 年岗）

解读：别被这堆词吓住------本系列初级章 + 中级（一）（二）做完，这里大半基础项你都能讲清楚；等到中级（三）Function Calling 和后面的服务化章节做完，MCP / Tool Use / Agent 编排这些词才会真正变成你的可交付能力。

4. 把这三份 JD 翻译成"日常在做什么"

抽掉所有话术，这三份 JD 的共同交集就是下面 5 件事：

#	日常在做的事	你现在就具备的能力	你要新补的能力
1	接大模型 API（Python / Java / C++ 任选一）	主流语言 + HTTP + 异步 ✅	chat.completions 协议、messages/role
2	写高质量 Prompt（能落地，不是术语表）	---	system/user 分层、约束、结构化输出
3	做 RAG / 向量库 / 知识库	---	切文本、embedding、检索、注入 Prompt
4	把 AI 能力接进已有业务系统 / 工具链	业务模块拆分、接口设计、状态管理 ✅	Function Calling、Tool Use（中级三）
5	和算法 / 产品 / 硬件协作，把 AI 功能从设计走到上线	跨模块协作、需求拆解、稳定性治理 ✅	AI 场景下的不确定性处理

你盯着右边这列看一眼------这就是本章和中级 1~3 章要带你做的全部内容。

5. 薪资 × 经验参考（深圳，2025）

经验档	薪资区间	年薪（按 13--14 薪）	对应样本
1 年+ / 应届优秀	12--20K	15--28 万	---
1--3 年	15--35K × 13~14 薪	20--50 万	JD-②（22-35K）JD-③（15-25K）
3--5 年（进入中级档）	20--40K × 13~14 薪	26--56 万	本系列中级章

翻译一下：

• 初级档在深圳的年薪下限 ≈ 20 万，上限 ≈ 50 万；
• 这个薪资段和同年限的 Android / iOS 初级岗基本持平，没有"转 AI 降薪"的普遍现象；
• 35K 这档（JD-② 的上限）本质上已经顶到"名义初级 / 实际中级"的边界了。

6. 最后一段：你其实差得不多

把这三份 JD 里的要求全列出来：

• Python / Java / C++ 主流语言
• 真实线上系统开发与运维经验
• 工程化落地能力、问题拆解、方案设计
• 跨团队沟通协作
• 代码质量、技术文档、稳定性
• API 调用、Prompt、RAG、Agent 至少一类

左边 5 条，全是你原生出身就自带的肌肉记忆。

右边最后 1 条，就是本章接下来要带你跑通的那个 main_rag.py 。

下一节我们把这一层的"能力清单"完整列出来，然后开始写第一行代码。

三、初级 AI Agent 工程师的能力清单

先给你一张清单。它就是你"过关"的硬标准：

#	能力	说明
1	会接大模型 API	OpenAI / Qwen / Claude 至少跑通一家，知道 model / messages / temperature 是什么
2	懂 LLM 心智	知道 token、上下文窗口、三种 role、幻觉这些工程师必须懂的基础
3	会写基础 Prompt	能用 system / user 分层约束模型，能让它按你的风格、格式、边界输出
4	能跑通 Agent 工作流	输入 → Prompt 组装 → LLM 调用 → 结果解析 → 输出
5	能做基础 RAG	会切文本、做向量、存向量库、做相似度检索、把结果注入 Prompt
6	能做最小 Demo	能把上面的东西整合成一个可交互的程序，不只是片段代码

注意：这一档不要求你"全会"流式输出、工具调用、多轮记忆、服务化封装------那些是中级 6 章要深挖的。

但你已经在上一节的 JD 拆解里看到，很多 1--3 年岗位里这些词已经被当成"期望项"写进要求了。所以初级这一档你必须做到两件事：

1. 把上面 6 条能力里至少一条做到能讲清楚、能复现（对应很多 JD 里那句"做过 API 调用、提示词工程、RAG、模型微调、Agent 等至少一类"）；

2. 把后面这些"中级词"先建立认知------知道它们是什么、为什么需要、中级哪几章会带你做。

初级不是"只会 1 个"，是"有 1 个能打的点 + 1 张完整的地图"。

四、必须先懂的 LLM 与 Prompt 基础概念

这些概念是后面每一章的"公共依赖"，一次讲清楚。

LLM 是什么

一句话：一个基于上下文预测下一个 token 的模型。

你不需要懂 Transformer，但必须把它当成一个"概率文字接龙引擎"，而不是一个"真理引擎"。

这个心智决定了你后面所有的工程选择。

Token

Token 是模型处理文字的最小单位：

• 英文 1 token ≈ 4 个字符
• 中文 1 个汉字通常 1~2 个 token

为什么工程师必须在乎 token？

• 价格按它算
• 速度按它算
• 上下文窗口按它算

不管 token，就等于写 App 不管内存。

上下文窗口

每个模型有最大长度限制（8k / 32k / 128k / 1M）。这是你后面所有工程决策的物理边界：

• 聊得太长，老信息会被挤掉
• 知识塞太多，模型抓不住重点
• 解决办法：截断、摘要、检索（就是 RAG 要解决的事）

三种角色：system / user / assistant

所有对话式模型的"协议底层"：

• system：角色设定、行为约束
• user：用户输入
• assistant：模型历史回答

后面所有高级玩法（记忆、工具调用、Agent 编排）都绕不开这三个角色。

⚠ 这里补一个小前瞻：其实还有第四种 role ------ tool，专门用来回传工具调用结果。

初级这一章我们不展开它，但你先把"三种角色 + 一个 tool"记在脑子里。

等到中级（三）Function Calling 时，你会发现很多 JD 里写的"深刻理解 Function Calling 原理"，本质上就是在考你对这层协议到底有没有看懂。

Temperature

输出随机性：

• 0.0：最稳定，适合结构化输出、代码、判断
• 0.3 左右：大多数 Agent 场景的默认
• 1.0+：创意发散

工程上你常用的是 0.2 ~ 0.4。

幻觉

模型会一本正经地胡说八道。工程上三板斧：

• Prompt 约束：明确要求"没把握就说不知道"
• RAG 注入：给它可靠资料（这章就要练）
• 输出校验：结构化输出 + 字段校验（中级篇展开）

记住：LLM 不是真理引擎，是文字生成引擎。

五、Agent 的最小工作流（Agent 版"四大组件"）

开篇提到过，这一节把它落地。

任何 AI Agent，不管多复杂，都跑不出这五步：

用户输入 → Prompt 组装 → LLM 调用 → 结果解析 → 输出呈现

对应到工程上：

步骤	在做什么	后续进阶方向
1. 用户输入	接收自然语言、语音、事件、传感器数据	多模态、设备数据接入
2. Prompt 组装	把 system + 历史 + 知识 + 用户输入拼成模型输入	记忆系统、RAG、上下文管理
3. LLM 调用	调大模型 API，拿回文本	流式、工具调用、多 Agent
4. 结果解析	把模型输出变成可用的结构化数据	JSON Schema、动作指令
5. 输出呈现	给用户 / 调用工具执行	消息流、卡片流、行为引导

这张表是贯穿整个系列的锚点。后面每章你都可以问自己：

"我现在是在优化工作流的哪一步？"

不问这句话，你会学成一堆散 trick；问了这句话，你能看见整张地图。

六、技术选型：为什么本系列不用 LangChain

很多 AI 应用教程一上来就用 LangChain，但本系列选择直接用官方 SDK。理由必须讲清楚。

LangChain 是什么

一个把 LLM 常用能力（调用、Prompt、记忆、RAG、工具调用、Agent 编排）打包好的框架。生态全、例子多。

为什么本系列不用它

• 抽象过深：很多封装让你看不到真实协议，排错困难
• API 迭代快：去年的例子今年跑不起来是常态
• 过度教学依赖：你会"用 LangChain"，但不会"做 Agent"
• 生产不一定首选：严肃项目里，官方 SDK + 自研封装是更主流的选择

本系列的立场

• 初级 → 直接用官方 openai SDK（DashScope 兼容 OpenAI 协议）
• 中级 → 按需引入轻量工具（如 qdrant-client、LlamaIndex RAG 部分）
• 高级 → 官方 SDK + 自己封装的 Agent 框架，贴近真实线上架构

换模型厂商时只需要改两行：base_url + model。这比任何框架都稳。

项目里原本有一个 main.py 使用了 langchain_openai ，我没删它，保留为"原始原型"，后面某一章会专门拿它做一次 "从 LangChain 到去 LangChain 的重构演化" 对照教学。这是很好的工程能力素材。

给你提前打一针

你大概率会在真实 JD 上看到"熟悉 LangChain / LangGraph / AutoGen 等主流 Agent 框架"的字样（上一节的 JD 拆解里就有类似原文）。

这件事的正确理解是：

• "熟悉"不等于"只会用"。你要能讲清楚这些框架在帮你做什么、替你抽象了什么、代价是什么；
• 本系列先让你不用框架把东西搓出来。等你手上有了官方 SDK 版本的 RAG / Memory / Tool Use，再去看 LangChain，你会发现它的每一层封装你都能翻译回"它其实在调什么原生 API"；
• 这才是 JD 上写"熟悉"两个字的真正含金量------不是会调它的 API，而是能在它和原生之间自由切换。

所以初级这一章你只管用官方 SDK 把 Demo 跑通；"会不会某个框架"这件事，放到中级阶段再专门对照着看。

七、环境准备

Python

建议 3.10 / 3.11。

虚拟环境

python -m venv .venv
source .venv/bin/activate           # macOS / Linux
# Windows: .venv\Scripts\activate

安装依赖

# 第一步 Demo 只需要这两个
pip install openai python-dotenv

# 第二步 Demo 额外需要
pip install qdrant-client sentence-transformers pypdf

配置 API Key

项目根目录新建 .env：

DASHSCOPE_API_KEY=你的阿里云百炼 Key

（本系列统一用 Qwen/百炼：国内访问稳、免费额度够用。换 OpenAI/Claude 只改两行即可。）

八、第一步 Demo：最小 LLM 问答（main_beginner.py）

先把工作流的前三步跑通。

# -*- coding: utf-8 -*-
"""
初级 AI Agent 工程师 · 最小可运行版本
"""

import os
from dotenv import load_dotenv
from openai import OpenAI


load_dotenv()
api_key = os.getenv("DASHSCOPE_API_KEY")
if not api_key:
    raise ValueError("请在 .env 中配置 DASHSCOPE_API_KEY")


client = OpenAI(
    api_key=api_key,
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)


SYSTEM_PROMPT = "你是一个智能助手，请用简洁清晰的中文回答用户的问题。"


def chat_once(question: str) -> str:
    response = client.chat.completions.create(
        model="qwen-plus",
        messages=[
            {"role": "system", "content": SYSTEM_PROMPT},
            {"role": "user", "content": question},
        ],
        temperature=0.3,
    )
    return response.choices[0].message.content or ""


def main() -> None:
    print("🤖 初级 Agent 已启动，输入 'quit' 退出\n")
    while True:
        user_input = input("👉 你: ").strip()
        if not user_input:
            continue
        if user_input.lower() == "quit":
            break

        answer = chat_once(user_input)
        print(f"\n🤖 Agent: {answer}\n")


if __name__ == "__main__":
    main()

对应到工作流：

• 用户输入：input()
• Prompt 组装：messages 数组（system + user）
• LLM 调用：client.chat.completions.create(...)
• 结果解析：response.choices[0].message.content
• 输出呈现：print

这 50 行是你整条学习路径的"锚代码"。后面每一章都是在增强其中某一步。

⚠️ 这版本不能做的事很多：不记事、不会查资料、不会办事。 下面我们就补最核心的一块：让它会查资料。

九、第二步 Demo：最小 RAG Agent（main_rag.py）

为什么要做 RAG

大模型有两个天生的短板：

• 不知道你的私有信息（公司内部文档、设备数据、项目资料）
• 会幻觉（你问私有问题它也会硬编）

RAG（Retrieval-Augmented Generation，检索增强生成）的核心思想很简单：

查到相关资料 → 塞给模型 → 让它基于资料回答。

听起来朴素，但这是过去两年几乎所有 AI 应用都绕不过的地基。

最小 RAG 的 5 个动作

动作	在 main_rag.py 里对应
① 读取知识库（文本/md/pdf）	QdrantRAG.load_documents
② 文本切分（chunk + overlap）	chunk_text
③ 向量化（embedding）	sentence-transformers 的 bge-small-zh-v1.5
④ 向量存储与检索	QdrantClient（本地持久化模式）
⑤ 注入 Prompt 并生成	build_user_message + client.chat.completions.create

文件结构

qwen-langchain-agent/
├── .env                      # DASHSCOPE_API_KEY
├── main_beginner.py          # 第一步 Demo
├── main_rag.py               # 第二步 Demo（本章交付物）
├── main.py                   # 老版本（LangChain 原型，对照用）
├── knowledge_base/           # 放你的 .txt / .md / .pdf
│   └── demo.md
├── qdrant_db/                # Qdrant 自动生成（本地向量库）
└── .rag_index_meta.json      # 自动生成（增量索引元数据）

自己准备几个 .md 或 .txt 丢进 knowledge_base/ 就可以跑。内容可以是你自己的读书笔记、项目文档、甚至一些小说段落。

代码关键点讲解

① 文本切分用 chunk + overlap

# main_rag.py · chunk_text
def chunk_text(text: str, chunk_size: int = 400, overlap: int = 80) -> List[str]:

② 用稳定 ID 支持幂等更新

point_id = str(uuid.uuid5(uuid.NAMESPACE_URL, f"{source}:{idx}"))

基于 source:chunk_id 生成 UUID，同一 chunk 每次都是同一个 ID，upsert 时自然覆盖，不会有脏数据残留。 这是工程师视角、不是 demo 视角的细节，你面试时讲得出来就是加分项。

③ 增量索引：基于文件 hash

if old_hash == file_hash:
    continue
changed_sources.add(source)

每个文件存一个 sha256，只有内容真变了才重建。知识库几百个文件时这个优化是刚需。

④ Prompt 里强制可追溯 + 防幻觉

SYSTEM_PROMPT = (
    "你是一个严谨的知识助手。"
    "请优先基于用户提供的参考资料作答；"
    "如果资料不足，请明确说明『资料中未找到充分信息』，不要编造。"
    "回答简洁，并在最后列出使用到的来源文件名。"
)

这段 Prompt 在做三件事：

• 行为约束：优先基于资料
• 幻觉兜底：资料不足必须说出来
• 可追溯性：必须报出来源

这三条是 RAG 工程里最基础但最容易被忽视的。

运行方式

# 确保已安装依赖
pip install openai python-dotenv qdrant-client sentence-transformers pypdf

# 第一次运行会下载 embedding 模型（~100MB），稍等一下
python main_rag.py

跑起来你会看到：

📚 Qdrant RAG 索引已就绪，chunk 数量: N
🤖 初级 RAG Agent 已启动！输入 'quit' 退出

👉 你: ...

🤖 Agent: ...

📎 检索来源: xxx.md

恭喜你，你已经亲手做出了一个能做"基于私有知识库回答"的 Agent。

这就是开篇里说的 "最小 RAG Agent Demo"。

十、这个版本能做什么、不能做什么

能做

• 基于你的私有知识库回答问题
• 引用来源、防幻觉
• 增量更新索引，不用每次全重建
• 换模型厂商只改两行配置

还不能做（对应后续章节）

缺失能力	表现	对应章节
多轮上下文	记不住"上一句说的是谁"	中级（一）：多轮对话与上下文管理
流式输出	必须等整段生成完才显示	中级（二）：SSE / Streaming
工具调用	只会说话，不会做事	中级（三）：Function Calling
检索优化	检得不准、排得不好	中级（四）：Rerank / 混合检索 / Query 改写
服务化	不能给 App 或前端调用	中级（五）：服务化封装与协议设计
稳定性治理	超时、重试、兜底全没有	中级（六）：工程化治理
评测体系	不知道自己做得好不好	高级：评测与优化

这张表就是你从初级走向中级的路线图。

注意：把这张路线图和前面 JD 拆解节里的关键词频次表放在一起看，你会发现几乎完全对上------多轮上下文、流式输出、工具调用、检索优化、服务化。

这不是巧合。

这就是市场在告诉你：做完 main_rag.py 之后，你已经踩住了初级 AI Agent 工程师的入门线；而要真正接住更多 1--3 年岗位，后面这几章的工程化能力必须继续补齐。

十一、本章小作业（建议做完再进入中级）

过关标准不是"跑通代码"，而是"讲得清楚"。

1. 温度实验：把 temperature 改成 0.0 / 0.5 / 1.0 各跑一次，记录同一个问题三组输出差异。
2. 角色实验：改 SYSTEM_PROMPT，让 Agent 扮演"严格的健康教练"或"刻薄的代码 reviewer"，观察风格变化。
3. 知识库实验：往 knowledge_base/ 里加一份你真实的笔记（读书 / 项目 / 工作），问它相关问题，感受 RAG 带来的差别。
4. chunk 策略实验：把 chunk_size 调成 200 / 800 各试一次，记录检索质量变化。
5. 讲解挑战：用自己的话，画一张"这份 Demo 的工作流图"，标清楚每一步对应 main_rag.py 里的哪个函数。
6. JD 对照挑战：打开 Boss 直聘，搜"AI 应用开发工程师 · 1--3 年"，任选 3 份岗位 JD，对照问自己：

• 这份 JD 里出现的每一个技术关键词（Prompt / RAG / Agent / MCP / 工具调用 / 多轮 / 流式 / Function Calling / 向量库......），我现在能不能在 main_rag.py 里指出对应实现？

• 如果不能，它属于"初级能力清单"6 条里的哪一条空缺？还是应该归到"中级章节路线图"里？

• 如果让你用 3 分钟向面试官介绍 main_rag.py，你会怎么按这份 JD 的关键词顺序组织讲解？

能完成第 5 项，你就真的过了代码这一关。

能完成第 6 项，你就开始具备"拿 Demo 对照 JD 讲能力"的意识了。

十二、下一篇预告

下一篇正式进入中级：

《中级（一）：从"会说话"到"会记事" ------ 多轮对话与上下文管理》

我们会把 main_rag.py 升级为能记住历史、能控制上下文窗口、会做记忆摘要的"会记事的 Agent"。

这是从"调 API 的人"走向"做 Agent 的人"的真正分水岭。

十三、写在最后

回到开篇那三句话：

1. AI Agent 不是玄学，它就是一门新工程。原生开发者迁移过来不难，难的是没人带。
2. 真正的门槛不是模型，是工程化落地能力。这恰好是你最擅长的那部分。
3. 这个系列从第一篇到最后一篇都免费，你要做的只有一件事 ------ 跟着练。

这一章结束，你应该已经：

• 手上有一个能跑的最小 RAG Agent Demo
• 心里有一张完整的 Agent 工作流地图
• 口里能讲清楚"初级"的边界和下一步要补什么

这就是初级过关。

下一篇见。