Agent 开发全景与路线图

这个系列回答一个问题：怎么从零动手开发一个能上生产的 AI Agent 应用。

定位区分：AI Agent Harness 系列讲「运行时系统怎么工作」，LangChain/LangGraph讲「框架怎么用」。本系列讲开发工程路线——以原生 SDK 为主线，从需求分析到部署监控。

一、先想清楚：你真的需要 Agent 吗

Agent 不是万能锤。用错档位 = 花更多的钱、得到更不可控的结果。

自主性阶梯

L0  单次 LLM 调用      翻译、摘要、改写 —— 一次 in、一次 out
L1  Chain（链）        固定步骤串联：翻译→校对→排版
L2  Workflow（工作流）  代码写死的分支路由：if 分类==投诉 → 走工单模板
L3  Agent（代理）       模型自己决定下一步调什么工具、何时结束
L4  Multi-Agent        多个 agent 协作/制衡/分工

关键原则：自主性是成本，不是功能。 能用 L2 解决的问题不要上 L3——工作流可测试、可复现、便宜；agent 灵活但不可预测。

选型决策树

任务步骤能提前枚举完吗？
  ├─ 能，且分支确定 ──────────────→ L1/L2：代码编排（最稳最便宜）
  ├─ 能，但每步需要智能判断 ──────→ L2：固定流程 + 每步一次 LLM 调用
  └─ 不能（取决于中间结果）────────→ 需要看中间数据决定走哪
       ├─ 简单（读个文件、查个库）→ L3：单 agent + 少量工具
       └─ 复杂（子任务异构、需并行）→ L4：多 agent 编排

真实例子：

场景	正确档位	为什么
周报生成	L1	输入输出固定，串联即可
客服意图分类 + 转接	L2	类别可枚举，路由确定
编程助手（读码、改码、跑测试）	L3	步骤完全取决于代码现状
「多视角评审一个方案」	L4	需要独立视角 + 汇总判断

二、Agent 应用的技术拼图

开发一个完整 agent 应用，要处理的面：

┌──────────────────────────────────────────────┐
│  应用层：CLI / Web UI / API 服务 / 消息机器人    │
├──────────────────────────────────────────────┤
│  编排层：agent loop / 工具路由 / 多 agent 协作   │
├──────────────────────────────────────────────┤
│  能力层：工具（function calling）、RAG 检索、    │
│         结构化输出、记忆、子代理                 │
├──────────────────────────────────────────────┤
│  模型层：LLM API（messages、流式、缓存）         │
├──────────────────────────────────────────────┤
│  基础设施：会话存储、观测 tracing、评估、限流     │
└──────────────────────────────────────────────┘

本系列的推进顺序就是自底向上把每一层打通：

篇目	覆盖
02 第一个 Agent	模型层 + 最小编排：原生 API 手写 loop
03 工具开发实战	能力层核心：设计、实现、测试工具
04 结构化输出	让模型输出可直接被程序消费
05 记忆与状态	会话管理、压缩、长期记忆
06 多 Agent 编排	编排层进阶：router/supervisor/debate
07 生产化工程	基础设施：流式服务、观测、评估、成本
08 综合实战项目	三个端到端项目串起全部知识

三、技术栈选择：原生 SDK vs 框架 vs 低代码

路线 A：原生 SDK（openai / anthropic 官方库）
  ✅ 完全掌控 loop 逻辑、零黑盒、调试直观
  ✅ 理解原理后学任何框架都很快
  ❌ 记忆/重试/观测都要自己写
  适合：学习阶段、定制化要求高的核心业务

路线 B：编排框架（LangGraph / CrewAI / AutoGen）
  ✅ 状态图、持久化、HITL 现成
  ❌ 抽象有学习成本，出问题要翻源码
  适合：复杂多 agent 流程、快速原型
  → 详见 [LangChain/LangGraph 笔记](../langchain-langgraph.md)

路线 C：Agent SDK（claude-agent-sdk / openai-agents）
  ✅ 工具集、权限、子代理、会话管理开箱即用
  适合：构建「类 Claude Code」的执行型 agent

路线 D：低代码平台（Dify / Coze）
  ✅ 拖拽搭建、分钟级上线
  ❌ 复杂逻辑受限、难做深度定制与测试
  适合：内部工具、MVP 验证

本系列的主线是路线 A——用原生 SDK 手写一切，理解每个零件；框架篇（06）会在关键处标注「这件事 LangGraph 里对应什么」。

四、开发环境准备

# Python 路线（本系列示例以 Python 为主，附 TS 对照）
pip install anthropic openai       # 官方 SDK 二选一或都装
pip install pydantic               # 结构化输出校验
pip install fastapi sse-starlette  # 07 篇：流式 API 服务

# TS/Node 路线
npm install @anthropic-ai/sdk zod

# .env —— 密钥永远不进代码
# ANTHROPIC_API_KEY=sk-ant-xxx
import os
from anthropic import Anthropic

client = Anthropic()  # 自动读环境变量

工程化清单（第一天就配，别等出事）：

□ API key 走环境变量 / secret manager
□ 所有 LLM 调用包一层：统一的日志 + 重试 + 超时
□ token 用量与费用打点（哪怕只是 log）
□ 一次调用设置 max_tokens 与轮数上限
□ 建立 eval 集：10 个典型任务 + 期望结果（会随开发不断扩充）

五、Agent 开发的心智模型

从「调 API 的人」到「agent 开发者」的三个转变：

1. 从「一次性调用」到「持续会话」
   你的代码不再是一次 request/response，
   而是维护一个随任务演进的 messages 状态机

2. 从「写逻辑」到「写提示 + 写工具」
   行为一半由系统提示和工具描述决定——
   它们是代码的一部分，要走版本管理、要走评审

3. 从「确定性测试」到「概率性评估」
   单测覆盖工具与编排逻辑；模型行为用 eval 集回归
   → 详见 [Harness 评估篇](../agent-harness/08-eval-safety-cost.md)

本篇小结

• 先用自主性阶梯选档位：能低不高，agent 的灵活性是拿可控性换的
• 技术拼图五层：应用 / 编排 / 能力 / 模型 / 基础设施
• 技术栈四路线：本系列主线是原生 SDK 手写，框架与 SDK 在对照中学习
• 工程化清单第一天就配：密钥、日志、费用打点、上限、eval 集

下一篇：第一个 Agent：从零手写。