AI Agent 开发完整教程：从零到上线的实战指南

我用 AI Agent 跑了三个月业务，从内容生产到数据分析全自动化。很多人问我怎么做的，今天把完整开发流程写出来。

这不是理论文章，是真实踩坑后的经验总结。你会看到：

• Agent 架构怎么设计才不会乱
• Prompt 怎么写才能稳定输出
• 记忆系统怎么搭建
• 多 Agent 怎么协作不打架
• 真实案例和可复用代码

一、Agent 不是聊天机器人

很多人第一次做 Agent，把它当成"能调 API 的 ChatGPT"。这是最大的误区。

聊天机器人 ：你问一句，它答一句，对话结束就忘了。 AI Agent：有目标、有记忆、能主动规划、能调用工具、能自我纠错。

举个例子：

• 聊天机器人："帮我写篇文章" → 写完就结束
• AI Agent："帮我写篇文章" → 分析关键词 → 搜索资料 → 写初稿 → 检查 SEO → 发布到 5 个平台 → 记录数据 → 下次优化

核心区别 ：Agent 是一个持续运行的系统，不是一次性对话。

二、Agent 架构：三层设计法

我试过很多架构，最后发现这个最稳定：

┌─────────────────────────────────────┐
│  决策层 (Brain)                      │
│  - 理解任务                          │
│  - 制定计划                          │
│  - 选择工具                          │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│  执行层 (Hands)                      │
│  - 调用 API                          │
│  - 读写文件                          │
│  - 执行命令                          │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│  记忆层 (Memory)                     │
│  - 短期记忆（当前任务上下文）        │
│  - 长期记忆（历史经验和知识）        │
│  - 工作记忆（正在处理的数据）        │
└─────────────────────────────────────┘

为什么要分三层？

不分层的问题：Agent 容易"精神分裂"------一会儿在思考策略，一会儿在执行命令，一会儿又忘了刚才做了什么。

分层后的好处：

• 决策层专注"做什么"
• 执行层专注"怎么做"
• 记忆层保证"不会忘"

三、Prompt 工程：Agent 的操作系统

Agent 的 Prompt 不是简单的指令，是它的操作系统。

3.1 系统 Prompt 结构

# 身份定义
你是 [Agent 名字]，负责 [核心职责]。

# 核心能力
- 能力 1：具体描述
- 能力 2：具体描述
- 能力 3：具体描述

# 工作流程
1. 收到任务后，先 [第一步]
2. 然后 [第二步]
3. 最后 [第三步]

# 决策规则
- 遇到 X 情况 → 做 A
- 遇到 Y 情况 → 做 B
- 不确定时 → 做 C

# 输出格式
[具体格式要求]

# 禁止事项
- NEVER 做 X
- NEVER 做 Y

3.2 真实案例：内容发布 Agent

你是 Lucky，负责中文 SEO 内容生产和多平台发布。

核心能力：
- 根据关键词写 800-1500 字 SEO 文章
- 自动注入 UTM 追踪参数
- 发布到掘金、知乎、CSDN
- 记录发布结果

工作流程：
1. 收到关键词后，先搜索相关资料
2. 写文章（标题含关键词，STEPPS 评分 ≥40）
3. 在文末插入 Gumroad 产品链接（带 UTM）
4. 依次发布到各平台
5. 记录 URL 到 publish-log.json

决策规则：
- 如果平台 API 失败 → 切换到 Playwright 方案
- 如果文章 <800 字 → 补充内容后再发
- 如果某平台连续失败 3 次 → 跳过并记录

输出格式：
汇报时用表格：
| 平台 | 状态 | URL |

3.3 Prompt 调优技巧

问题 1 ：Agent 输出不稳定，有时好有时差。 解决：加具体示例。不要只说"写好文章"，给一个标准示例。

问题 2 ：Agent 经常"忘记"之前的指令。 解决 ：关键规则用 ALWAYS 和 NEVER 强调，放在 Prompt 最前面。

问题 3 ：Agent 遇到错误就卡住。 解决：写清楚降级策略。"如果 A 失败 → 尝试 B → 还失败 → 跳过并记录"。

四、记忆系统：Agent 的大脑

没有记忆的 Agent 是"金鱼"，每次都从零开始。

4.1 三种记忆

记忆类型	存储内容	保留时间	实现方式
短期记忆	当前任务上下文	单次对话	LLM 上下文窗口
工作记忆	正在处理的数据	任务周期	临时文件/变量
长期记忆	历史经验和知识	永久	向量数据库/文件

4.2 长期记忆实现

最简单的方案：结构化文件 + 语义搜索

memory/
├── MEMORY.md              # 核心知识（手动维护）
├── 2026-03-17.md          # 今天的工作日志
├── 2026-03-16.md          # 昨天的工作日志
├── corrections.md         # 错误和纠正记录
└── publish-log.json       # 结构化数据

MEMORY.md 示例：

## 内容发布经验

### 掘金
- 标题不能超过 30 字
- 必须选 3-5 个标签
- 发布后 2 小时内编辑不影响推荐

### 知乎
- 首图很重要，影响点击率
- 回答问题比发文章流量大
- 避免敏感词：翻墙、VPN、破解

### CSDN
- API 经常 403，用 Playwright 更稳定
- 原创标签需要审核
- 代码块用 ``` 包裹

4.3 记忆检索

Agent 开始工作前，先搜索相关记忆：

# 伪代码
def start_task(keyword):
    # 1. 搜索长期记忆
    relevant_memory = search_memory(keyword)
    
    # 2. 加载到上下文
    context = f"相关经验：\n{relevant_memory}\n\n当前任务：{keyword}"
    
    # 3. 执行任务
    result = agent.run(context)
    
    # 4. 更新记忆
    save_to_memory(result)

五、工具调用：Agent 的手

Agent 的能力取决于它能调用什么工具。

5.1 工具设计原则

原则 1：一个工具只做一件事

• ❌ publish_article(platform, content)
• ✅ publish_to_juejin(content) + publish_to_zhihu(content)

原则 2：工具要有清晰的输入输出

def publish_to_juejin(title: str, content: str, tags: list) -> dict:
    """
    发布文章到掘金
    
    Args:
        title: 文章标题
        content: Markdown 内容
        tags: 标签列表（3-5个）
    
    Returns:
        {
            "success": True/False,
            "url": "文章链接",
            "error": "错误信息（如果失败）"
        }
    """

原则 3：工具要有降级方案

def publish_to_devto(content):
    try:
        # 方案 1：API
        return api_publish(content)
    except APIError:
        # 方案 2：Playwright
        return playwright_publish(content)
    except Exception as e:
        # 方案 3：记录失败
        log_error(e)
        return {"success": False, "error": str(e)}

5.2 常用工具类型

工具类型	示例	用途
搜索工具	Google Search API, Tavily	获取实时信息
文件工具	read_file, write_file	读写本地数据
API 工具	各平台发布 API	对接外部服务
浏览器工具	Playwright, Puppeteer	自动化操作网页
数据工具	JSON 解析, CSV 处理	结构化数据处理

六、多 Agent 协作：分工不打架

单个 Agent 能力有限，多个 Agent 协作才能干大事。

6.1 协作模式

模式 1：流水线（Pipeline）

Agent A（写文章）→ Agent B（SEO 优化）→ Agent C（发布）

适合：固定流程的任务

模式 2：并行（Parallel）

任务 → Agent A（掘金）
     → Agent B（知乎）
     → Agent C（CSDN）

适合：独立子任务

模式 3：主从（Master-Worker）

Master Agent（协调）
  ↓
Worker Agent 1（执行）
Worker Agent 2（执行）
Worker Agent 3（执行）

适合：复杂任务分解

6.2 协作关键：消息传递

Agent 之间通过结构化消息通信：

{
  "from": "agent_a",
  "to": "agent_b",
  "task": "publish_article",
  "data": {
    "title": "文章标题",
    "content": "文章内容",
    "platform": "juejin"
  },
  "priority": "high",
  "deadline": "2026-03-17 12:00"
}

6.3 避免冲突

问题 ：多个 Agent 同时写同一个文件 → 数据丢失 解决：文件锁机制

import fcntl

def safe_write(file_path, content):
    with open(file_path, 'w') as f:
        fcntl.flock(f, fcntl.LOCK_EX)  # 加锁
        f.write(content)
        fcntl.flock(f, fcntl.LOCK_UN)  # 解锁

七、错误处理：Agent 不能"死机"

Agent 在生产环境会遇到各种意外，必须有容错机制。

7.1 错误分类

错误类型	处理策略	示例
可重试错误	重试 3 次，指数退避	网络超时、API 限流
可降级错误	切换备用方案	API 失败 → Playwright
致命错误	记录并跳过	账号被封、文件不存在

7.2 重试机制

import time

def retry(func, max_attempts=3, backoff=2):
    for attempt in range(max_attempts):
        try:
            return func()
        except Exception as e:
            if attempt == max_attempts - 1:
                raise e
            wait_time = backoff ** attempt
            time.sleep(wait_time)

7.3 监控和告警

Agent 运行时要记录关键指标：

{
  "date": "2026-03-17",
  "agent": "lucky",
  "tasks_total": 10,
  "tasks_success": 8,
  "tasks_failed": 2,
  "errors": [
    {"platform": "csdn", "error": "403 Forbidden", "retry": true},
    {"platform": "zhihu", "error": "账号封禁", "retry": false}
  ]
}

八、实战案例：内容发布 Agent

把前面的知识串起来，看一个完整案例。

8.1 需求

自动化中文 SEO 内容生产和发布：

1. 根据关键词写文章（800-1500 字）
2. 自动注入 UTM 追踪
3. 发布到掘金、知乎
4. 记录发布结果

8.2 架构设计

┌─────────────────────────────────────┐
│  ContentAgent (决策层)               │
│  - 分析关键词                        │
│  - 规划文章结构                      │
│  - 选择发布平台                      │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│  WriterTool (执行层)                 │
│  - 搜索资料                          │
│  - 生成文章                          │
│  - 注入 UTM                          │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│  PublishTool (执行层)                │
│  - 掘金发布                          │
│  - 知乎发布                          │
│  - 错误重试                          │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│  MemoryStore (记忆层)                │
│  - 发布历史                          │
│  - 平台规则                          │
│  - 错误记录                          │
└─────────────────────────────────────┘

8.3 核心代码

class ContentAgent:
    def __init__(self):
        self.writer = WriterTool()
        self.publisher = PublishTool()
        self.memory = MemoryStore()
    
    def run(self, keyword):
        # 1. 搜索相关记忆
        context = self.memory.search(keyword)
        
        # 2. 生成文章
        article = self.writer.generate(
            keyword=keyword,
            context=context,
            min_words=800
        )
        
        # 3. 注入 UTM
        article = self.inject_utm(article)
        
        # 4. 发布到各平台
        results = {}
        for platform in ['juejin', 'zhihu']:
            try:
                url = self.publisher.publish(platform, article)
                results[platform] = {'success': True, 'url': url}
            except Exception as e:
                results[platform] = {'success': False, 'error': str(e)}
        
        # 5. 保存记忆
        self.memory.save({
            'keyword': keyword,
            'article': article,
            'results': results,
            'timestamp': datetime.now()
        })
        
        return results

8.4 运行效果

输入：关键词 "Agent开发教程"

输出：
| 平台 | 状态 | URL |
|------|------|-----|
| 掘金 | ✅ | https://juejin.cn/post/xxx |
| 知乎 | ✅ | https://zhuanlan.zhihu.com/p/xxx |

文章字数：1247
STEPPS 评分：42/60
发布时间：2026-03-17 09:30

九、进阶技巧

9.1 动态 Prompt

根据任务类型动态调整 Prompt：

def get_prompt(task_type):
    base_prompt = "你是内容发布 Agent..."
    
    if task_type == "technical":
        return base_prompt + "\n专注技术深度，多用代码示例。"
    elif task_type == "tutorial":
        return base_prompt + "\n用通俗语言，多用类比和图表。"
    else:
        return base_prompt

9.2 自我优化

Agent 根据历史数据优化自己：

def optimize_strategy(self):
    # 分析过去 30 天的发布数据
    stats = self.memory.get_stats(days=30)
    
    # 找出表现最好的平台
    best_platform = max(stats, key=lambda x: x['engagement'])
    
    # 调整发布优先级
    self.priority = [best_platform] + [p for p in self.platforms if p != best_platform]

9.3 人机协作

不是所有事都要全自动，关键决策让人来：

def publish_with_approval(article):
    # 1. Agent 生成文章
    draft = agent.generate(article)
    
    # 2. 发给人类审核
    approved = human_review(draft)
    
    # 3. 人类批准后再发布
    if approved:
        return agent.publish(draft)
    else:
        return agent.revise(draft, feedback)

十、常见坑和解决方案

坑 1：Token 超限

问题 ：上下文太长，超过 LLM 限制。 解决：

• 压缩历史对话（只保留关键信息）
• 用向量数据库存长期记忆
• 分段处理长文本

坑 2：幻觉（Hallucination）

问题 ：Agent 编造不存在的信息。 解决：

• 要求 Agent 引用来源
• 关键信息用工具验证
• 加入"不确定时说不知道"的规则

坑 3：死循环

问题 ：Agent 陷入重复操作。 解决：

• 设置最大步数限制
• 检测重复操作并中断
• 加入"如果 3 次尝试都失败就放弃"的规则

坑 4：成本失控

问题 ：API 调用太多，费用爆炸。 解决：

• 缓存常用结果
• 用更便宜的模型处理简单任务
• 设置每日预算上限

总结

AI Agent 开发的核心：

1. 架构清晰：决策、执行、记忆分层
2. Prompt 精准：像写操作系统一样写 Prompt
3. 记忆完善：短期、工作、长期三种记忆
4. 工具可靠：有降级方案，能容错
5. 协作有序：多 Agent 通过消息传递协作
6. 持续优化：根据数据不断改进

最重要的：先跑起来，再优化。不要追求完美，先让 Agent 能工作，然后根据实际问题迭代。

我的 Agent 第一版也很烂，经过 3 个月迭代才稳定。你的第一版肯定也会有问题，但只要持续改进，最终会越来越好。

---

🎁 免费下载 ：AI Agent 开发工具包 --- Prompt 模板、架构图、代码示例

💰 完整资源 ：AI Agent 完整工具集 --- 省 70%