技术知识库

Appearance

aiagentmcpskilllearning

AI Agent 开发学习手册 ​

从技术支持工程师到 AI Agent 开发者的系统性学习路径。涵盖 Agent Loop、Skill 开发、MCP 协议、Harness Engineering。

概述 ​

学习路径总览 ​

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌───────────────┐
│  1. Agent    │───→│  2. Skill    │───→│  3. MCP      │───→│  4. Harness   │
│     Loop     │    │     开发      │    │     协议      │    │  Engineering  │
│              │    │              │    │              │    │               │
│  理解 Agent  │    │  结构化指令   │    │  标准化工具   │    │  生产级部署   │
│  底层原理    │    │  编排与复用   │    │  跨平台互通   │    │  可观测/安全  │
└──────────────┘    └──────────────┘    └──────────────┘    └───────────────┘
     1-2 周             1-2 周             1-2 周              持续

前置知识 ​

  • Python 基础（能写函数、懂类型注解）
  • 用过至少一种 AI 编程助手（Claude Code / Codex / Cursor）
  • 了解 HTTP API 的基本概念
  • 会用命令行

第一部分：Agent Loop — 理解 Agent 的心脏 ​

什么是 Agent Loop ​

Agent Loop 是 AI Agent 的核心执行引擎。它的本质只有三件事：

  1. LLM — 一个大语言模型，支持工具调用（Function Calling）
  2. 工具 — 一组普通函数，Agent 可以调用它们来做事
  3. 循环 — 一个 while 循环：调用 LLM → 执行工具 → 把结果喂回去 → 重复
python
# Agent Loop 的核心伪代码（完整实现见 agent-loop/agent_loop.py）
while step < MAX_STEPS:                    # 安全上限，防止死循环
    response = provider.chat(messages)      # 调用 LLM
    if not provider.is_tool_call(response): # LLM 说完了
        return response.text
    for tool_call in provider.extract_tool_calls(response):
        result = execute_tool(tool_call)    # 执行工具
    messages.append(result)                 # 结果追加到对话

和普通 LLM 聊天的区别 ​

普通 LLM 聊天Agent
只能回复文字能调用工具、执行操作
凭训练数据回答能查询实时数据
单轮对话多轮循环，自主决策
不会犯错（除了胡说）可能死循环，需要 max_steps 保护

动手实践 ​

配套代码：agent-loop/（本地路径：E:\code\paseo\agent-loop\）

bash
cd agent-loop
cp .env.example .env   # 编辑 .env 填入 API Key
pip install -r requirements.txt
python demo.py         # 四个场景对比演示

支持的后端：

  • Anthropic Claude（官方）
  • OpenAI（官方）
  • 任意 OpenAI 兼容接口（公司内部 API / OneAPI / vLLM / Ollama）

配置方式详见 .env.example。

Provider 抽象层设计 ​

Agent Loop 本身不依赖任何特定 LLM。所有差异通过 LLMProvider 接口封装：

差异点AnthropicOpenAI
工具格式input_schemafunction.parameters
结束信号stop_reason == "end_turn"finish_reason == "stop"
工具调用提取content[].type == "tool_use"message.tool_calls
工具结果格式{"type": "tool_result", ...}{"role": "tool", ...}

关键设计原则：Agent Loop 核心逻辑和具体 LLM 解耦。新增模型只需新增一个 Provider 类。

第二部分：Skill 开发 — 让 Agent 更专业 ​

Skill 是什么 ​

Skill 是结构化的 Agent 指令集（Markdown 文件），告诉 Agent 在特定场景下如何工作。它遵循 Agent Skills 开放标准。

Skill（你已会）           Agent Loop（你要学）       MCP（下一阶段）
   ↓                           ↓                        ↓
告诉 Agent 做什么            让 Agent 能动起来        让 Agent 能连接外部
prompt 模板                   LLM→工具→LLM 循环        标准化的工具协议

Skill 和 Agent Loop 的关系 ​

维度Skill（你已有 7 个）Skill + Agent Loop（升级后）
repo-test-analyst写 prompt 分析代码自动运行 pytest、解析结果、生成覆盖率
yolo-report-analyst写 prompt 分析训练结果自动调参、对比多轮训练、生成优化建议
thesis-doc-agent写 prompt 生成文档自动读取项目、运行分析、生成多份文档

核心区别：Skill 是"告诉 Agent 怎么做"，Agent Loop 是"让 Agent 能自主做事"。两者结合 = 专业级 AI 工具。

Skill 文件结构 ​

text
my-skill/
├── SKILL.md              # 核心指令（必需）
├── references/           # 参考资料（可选）
│   ├── templates.md
│   └── examples.md
├── README.md
└── CHANGELOG.md

好 Skill 的要素 ​

markdown
# ❌ 差的 Skill
你是一个代码分析助手，帮我分析代码。

# ✅ 好的 Skill
你是一个 Python 代码分析师。分析流程：
1. 先用 read_file 读取项目结构
2. 用 grep 搜索关键模式
3. 生成包含以下内容的报告：
   - 模块依赖关系（Mermaid 图）
   - 代码质量评分（复杂度、重复率）
   - 改进建议（按优先级排序）
4. 输出为 Markdown 格式

第三部分：MCP 协议 — 标准化的工具生态 ​

MCP 是什么 ​

Model Context Protocol（MCP）是 Anthropic 推出的开放标准，让任何 LLM 客户端都能通过统一接口调用外部工具。

没有 MCP:                          有了 MCP:
每个 AI 工具都要写一套集成          写一次 MCP Server，所有 AI 工具都能用

Claude ──→ 自定义代码 ──→ 数据库    Claude ─┐
Cursor ──→ 自定义代码 ──→ 数据库    Cursor ─┤
Codex  ──→ 自定义代码 ──→ 数据库    Codex  ─┼──→ MCP Server ──→ 数据库
Copilot──→ 自定义代码 ──→ 数据库    Copilot ─┘

MCP 和 Skill 的关系 ​

┌─────────────────────────────────────────┐
│              Skill（指令层）              │
│  "遇到问题 X 时，先搜索知识库，再创建工单" │
│                    ↓                     │
│              MCP Server（工具层）         │
│  search_knowledge_base()  create_ticket()│
│                    ↓                     │
│            实际系统（数据层）              │
│       数据库      API      文件系统       │
└─────────────────────────────────────────┘

MCP Server 示例（Python） ​

python
# 一个最小的 MCP Server（约 60 行）
from mcp.server import Server, NotificationOptions
from mcp.server.models import InitializationCapabilities

server = Server("my-tools")

@server.list_tools()
async def list_tools():
    return [
        {
            "name": "search_kb",
            "description": "搜索技术知识库",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"}
                },
                "required": ["query"]
            }
        }
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "search_kb":
        return [{"type": "text", "text": f"搜索结果: {arguments['query']}"}]

常见的 MCP Server ​

Server用途
GitHub MCP读写 Issues、PR、Commits
Postgres MCP数据库查询
Brave Search MCP网络搜索
Filesystem MCP文件系统操作
Harness MCPCI/CD 平台管理

第四部分：Harness Engineering — 从 Demo 到生产 ​

Harness 的两层含义 ​

A. Harness 平台：CI/CD 公司，他们做了 Skills + MCP 的最佳实践案例。

B. Harness Engineering（约束工程学）：把 Agent 从玩具变成生产系统的工程方法论。

Demo vs 生产级 ​

维度Demo 阶段生产级
错误处理没有每步都有 fallback + 重试
步骤上限无限制max_steps=10~25，超限告警
成本监控不关心每次调用记录 token 消耗
可观测性无每个 tool call 都记日志
权限控制完全开放分级权限，敏感操作需确认
沙箱隔离无文件/网络/进程隔离

成本控制 ​

python
# 生产级 Agent 的成本监控
class CostTracker:
    def __init__(self):
        self.total_tokens = 0
        self.total_cost = 0.0
        self.budget_limit = 5.0  # 每次任务最多 $5

    def track(self, response):
        tokens = response.usage.input_tokens + response.usage.output_tokens
        cost = self._calculate_cost(response.model, tokens)
        self.total_cost += cost
        if self.total_cost > self.budget_limit:
            raise BudgetExceededError(f"超出预算 {self.budget_limit}")

可观测性 ​

生产级 Agent 必须记录：

  • 每次 LLM 调用的输入/输出/耗时/token
  • 每次工具调用的参数/结果/耗时
  • 每次异常的堆栈和上下文
  • 用户反馈（成功/失败/满意度）

实践项目建议 ​

项目一：技术支持工单自动分类 Agent ​

场景：利用你现有的技术支持工作经验，做一个自动分类工单的 Agent。

技术栈：Python + Agent Loop + 公司内部 API

功能：

  1. 读取工单内容
  2. 自动分类（网络问题 / 系统故障 / 账号问题 / 咨询）
  3. 搜索知识库匹配已知解决方案
  4. 无法自动解决的，创建升级工单

项目二：知识库智能检索 Agent ​

场景：基于你已有的 VitePress 知识库，做一个能回答技术问题的 Agent。

技术栈：Agent Loop + MCP Server + 本地文件系统

功能：

  1. 用户用自然语言提问
  2. Agent 搜索知识库文档
  3. 如果没找到，搜索命令速查表
  4. 综合多个来源给出答案

项目三：部署到 Cloudflare Workers ​

场景：把 Agent 做成线上服务，团队都能用。

优势：你已有 CF Workers 经验，可以快速部署。

架构：

用户 → Cloudflare Workers（Agent 运行时）
         ├── D1（存日志/状态）
         ├── R2（存报告/附件）
         └── Workers AI / 外部 API（LLM 推理）

推荐学习顺序 ​

阶段内容时间产出
第 1-2 周手写 Agent Loop，理解底层原理10h可运行的 Agent Loop 代码
第 3-4 周升级一个 Skill，加入工具调用8h带工具调用的 Skill
第 5-6 周写第一个 MCP Server10h可用的 MCP Server
第 7-8 周MCP Server + Skill 打通8h端到端 Agent 工具链
第 9-12 周生产级 Agent 项目20h+开源项目 + 部署上线

参考资源 ​

官方文档 ​

学习资源 ​

配套代码 ​

数字化发展中心 · IT共享服务中心

Copyright © 2026