这份教程从"小白视角"出发——先讲清楚厂商 SDK、框架、MCP 三者到底是什么关系,再逐个深入。每个都配可运行代码 + 通俗类比。

---

厂商 SDK + MCP + Agent 框架 完全教程

开篇：先理清三者关系（小白必看）

很多人学晕,是因为没搞清这三层在哪一层：

┌─────────────────────────────────────────────┐
│  Agent 框架  (LangGraph/CrewAI/AutoGen)      │  ← 最上层：帮你编排
│  "我帮你管好多步流程、多个agent协作"          │
├─────────────────────────────────────────────┤
│  厂商 SDK  (OpenAI/Anthropic SDK)            │  ← 中间层：直接对话模型
│  "我是你和大模型之间的电话线"                 │
├─────────────────────────────────────────────┤
│  MCP 协议                                     │  ← 横向标准：工具怎么接
│  "我规定了 AI 怎么统一调用外部工具"           │
└─────────────────────────────────────────────┘

通俗类比（点外卖）：

• 厂商 SDK = 你直接打电话给餐厅点餐（原始、直接、灵活，但要自己说清楚每个细节）
• Agent 框架 = 用美团 App 点餐（帮你管好流程、推荐、下单，封装好了）
• MCP = 餐厅之间统一的"菜单标准格式"（不管哪家餐厅，菜单格式一样，AI 都能看懂）

学习顺序建议：先学厂商 SDK（懂原理）→ 再学 MCP（懂工具标准）→ 最后学框架（懂封装）。

---

第一部分：厂商 SDK（地基，必须懂）

1.1 为什么要学厂商 SDK

框架虽然方便,但：

• 框架是厂商 SDK 的封装,出问题你得懂底层才能 debug
• 简单需求用框架是"杀鸡用牛刀"
• 面试/进阶必问原理

结论：厂商 SDK 是"内功",框架是"招式"。

---

1.2 OpenAI SDK（最主流，国内很多兼容它）

安装

pip install openai

第一个对话（小白起步）

from openai import OpenAI

# 创建客户端（相当于建立和模型的连接）
client = OpenAI(
    api_key="sk-xxx",                          # 你的密钥
    base_url="https://api.openai.com/v1",      # 可换成国内兼容端点
)

# 发起对话
response = client.chat.completions.create(
    model="gpt-4o-mini",                       # 用哪个模型
    messages=[                                  # 对话消息列表
        {"role": "system", "content": "你是一个友好的助手"},
        {"role": "user", "content": "你好，介绍下你自己"},
    ],
)

# 取出回复
print(response.choices[0].message.content)

三个 role 是什么（小白重点）：

system    = 给AI设定角色（"你是面试官"），对话开头设一次
user      = 用户说的话
assistant = AI回复的话

多轮对话（关键：要自己维护历史）

# 大模型本身没有记忆，靠你把历史一起传过去
messages = [
    {"role": "system", "content": "你是一个助手"},
]

def chat(user_input):
    messages.append({"role": "user", "content": user_input})    # 加用户输入
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=messages,                                       # 传全部历史
    )
    reply = response.choices[0].message.content
    messages.append({"role": "assistant", "content": reply})    # 加AI回复
    return reply

print(chat("我叫小明"))
print(chat("我叫什么名字？"))     # AI 记得，因为历史都传过去了

流式输出（打字机效果）

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "讲个100字的故事"}],
    stream=True,                       # 开启流式
)

for chunk in stream:                   # 逐块接收
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

控制参数（小白调优）

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[...],
    temperature=0.7,        # 0-2，越高越有创意，越低越严谨（写代码用0，写诗用1）
    max_tokens=500,         # 最多生成多少token（控制长度和成本）
    top_p=1.0,              # 另一种随机性控制，一般不动
)

Function Calling 工具调用（Agent 核心）

这是 Agent 的灵魂——让模型自己决定调用你的函数：

import json

# 1. 定义你的真实函数
def get_weather(city: str) -> str:
    return f"{city}今天晴，25度"

# 2. 用 JSON Schema 描述这个函数给模型看
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询城市天气",       # 模型靠这个判断何时调用
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名"}
            },
            "required": ["city"],
        },
    },
}]

# 3. 第一次请求：模型决定要不要调工具
messages = [{"role": "user", "content": "北京天气怎么样？"}]
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    tools=tools,
)

msg = response.choices[0].message

# 4. 如果模型要调工具
if msg.tool_calls:
    messages.append(msg)                          # 把模型的决定加入历史
    for tool_call in msg.tool_calls:
        args = json.loads(tool_call.function.arguments)
        result = get_weather(**args)              # 真正执行你的函数
        # 把工具结果返回给模型
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": result,
        })

    # 5. 第二次请求：模型基于工具结果生成最终回答
    final = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=messages,
    )
    print(final.choices[0].message.content)       # "北京今天晴，25度..."

这个流程就是 Agent 的本质（记住这张图）：

用户问 → 模型判断要调工具 → 你执行工具 → 结果给模型 → 模型给最终答案
         └────────── 可能循环多次（调多个工具）──────────┘

结构化输出（让模型返回固定 JSON）

from pydantic import BaseModel

class UserInfo(BaseModel):
    name: str
    age: int
    city: str

# 用 parse 方法（自动校验成 Pydantic 对象）
response = client.beta.chat.completions.parse(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "提取：小明，25岁，住北京"}],
    response_format=UserInfo,
)
user = response.choices[0].message.parsed
print(user.name, user.age, user.city)    # 小明 25 北京

Embedding（向量化，RAG 用）

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="把这句话变成向量",
)
vector = response.data[0].embedding       # 一个浮点数列表（1536维）
print(len(vector))                        # 1536

---

1.3 Anthropic SDK（Claude）

Claude 的 SDK 和 OpenAI 略有不同,小白注意差异：

安装与基本对话

pip install anthropic

from anthropic import Anthropic

client = Anthropic(api_key="sk-ant-xxx")

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1000,                      # Claude 必须指定（OpenAI 可选）
    system="你是一个助手",                 # system 是独立参数，不在 messages 里！
    messages=[
        {"role": "user", "content": "你好"},
    ],
)
print(response.content[0].text)           # 注意取值方式不同

OpenAI vs Anthropic 关键差异（小白对照）

点	OpenAI	Anthropic
包名	openai	anthropic
调用方法	chat.completions.create	messages.create
system	放在 messages 里	独立 system 参数
max_tokens	可选	必填
取回复	.choices[0].message.content	.content[0].text

Claude 工具调用（Tool Use）

tools = [{
    "name": "get_weather",
    "description": "查询天气",
    "input_schema": {                     # 注意叫 input_schema（OpenAI叫parameters）
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1000,
    tools=tools,
    messages=[{"role": "user", "content": "北京天气？"}],
)

# 检查是否要调工具
for block in response.content:
    if block.type == "tool_use":
        print(block.name, block.input)    # get_weather {'city': '北京'}

---

1.4 国内厂商 SDK（大多兼容 OpenAI）

好消息：DeepSeek、通义千问、智谱、Kimi 等大多兼容 OpenAI 格式,只需改 base_url 和 model：

from openai import OpenAI

# DeepSeek（直接用 openai 包！）
client = OpenAI(
    api_key="your-deepseek-key",
    base_url="https://api.deepseek.com/v1",
)
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "你好"}],
)

# 通义千问
client = OpenAI(
    api_key="your-key",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
# model="qwen-plus"

# 智谱 GLM
client = OpenAI(
    api_key="your-key",
    base_url="https://open.bigmodel.cn/api/paas/v4",
)
# model="glm-4"

这也是你 Java 项目里 one-api 的思路：统一成 OpenAI 格式,换模型只改配置。

---

1.5 不用框架，手写一个 Agent（理解原理）

把前面的工具调用包成循环,你就手写了一个 Agent：

import json
from openai import OpenAI

client = OpenAI(api_key="sk-xxx")

# 工具库
def calculator(expression: str) -> str:
    return str(eval(expression))

def get_time() -> str:
    from datetime import datetime
    return datetime.now().strftime("%Y-%m-%d %H:%M")

TOOLS_MAP = {"calculator": calculator, "get_time": get_time}

tools_schema = [
    {"type": "function", "function": {
        "name": "calculator",
        "description": "计算数学表达式",
        "parameters": {"type": "object", "properties": {
            "expression": {"type": "string"}}, "required": ["expression"]},
    }},
    {"type": "function", "function": {
        "name": "get_time", "description": "获取当前时间",
        "parameters": {"type": "object", "properties": {}},
    }},
]

# Agent 循环（核心！）
def run_agent(user_input: str, max_steps: int = 5):
    messages = [{"role": "user", "content": user_input}]

    for step in range(max_steps):          # 最多循环几步（防死循环）
        response = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=messages,
            tools=tools_schema,
        )
        msg = response.choices[0].message

        # 没有工具调用 = 任务完成
        if not msg.tool_calls:
            return msg.content

        # 有工具调用 = 执行后继续循环
        messages.append(msg)
        for tc in msg.tool_calls:
            func = TOOLS_MAP[tc.function.name]
            args = json.loads(tc.function.arguments)
            result = func(**args)
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": str(result),
            })
            print(f"[第{step+1}步] 调用 {tc.function.name} → {result}")

    return "达到最大步数"

print(run_agent("现在几点？然后计算 25 * 4"))

这 30 行就是 Agent 的全部本质！ LangGraph、CrewAI 都是在这个循环上加花样。你的 Java 项目 auto 策略也是这个循环。

---

第二部分：MCP 协议（工具标准化）

2.1 MCP 是什么（小白理解）

MCP = Model Context Protocol（模型上下文协议）,Anthropic 2024 年底推出,现已成行业标准。

解决什么问题？

没有 MCP 时的痛点：

你的 Agent 想接 10 个工具（数据库、文件、搜索...）
→ 每个工具都要写一套对接代码
→ 换个 Agent 框架，全部重写
→ 一百个开发者，一百种写法

有了 MCP：

工具方按 MCP 标准写一次 "MCP Server"
→ 任何支持 MCP 的 Agent 都能直接用
→ 像 USB 接口：一个标准，到处通用

通俗类比：MCP 之于 AI 工具,就像 USB 之于电脑外设。以前每个设备不同接口,现在统一 USB,插上就能用。

---

2.2 MCP 架构（三个角色）

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│  MCP Host    │      │  MCP Client  │      │  MCP Server  │
│ (你的AI应用) │◄────►│  (连接器)    │◄────►│  (工具提供方)│
│ Claude/Cursor│      │              │      │ 文件/数据库  │
└──────────────┘      └──────────────┘      └──────────────┘
   想用工具的           中间协议层            真正干活的

• Host：AI 应用（如 Claude Desktop、Cursor、你的 Agent）
• Client：协议客户端（Host 内置,负责按 MCP 协议通信）
• Server：工具服务（提供具体能力,如操作文件、查数据库）

对照你的 Java 项目：McpSyncClient 就是 Client,@modelcontextprotocol/server-filesystem 就是 Server。

---

2.3 MCP 的三大能力

MCP Server 能提供三种东西：

1. Tools（工具）     —— 可执行的函数（查天气、写文件）★最常用
2. Resources（资源） —— 可读取的数据（文件内容、数据库记录）
3. Prompts（提示词） —— 预设的提示词模板

---

2.4 两种传输方式（你 Java 项目里见过）

stdio  —— 本地子进程通信（启动一个本地程序）
          适合：本地工具（文件操作、本地脚本）

SSE/HTTP —— 网络通信
          适合：远程工具服务（你项目的 CSDN 发帖 192.168.1.108:8101）

---

2.5 用现成的 MCP Server（最简单）

社区有几百个现成 Server,直接用：

# 官方 Server 示例（npm 包）
npx -y @modelcontextprotocol/server-filesystem /path/to/dir   # 文件操作
npx -y @modelcontextprotocol/server-github                     # GitHub
# 还有 数据库、搜索、地图等

在 Claude Desktop 配置（小白最快体验）：

// claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Desktop"]
    }
  }
}

配好后,Claude 就能直接读写你桌面的文件了。

---

2.6 自己写一个 MCP Server（Python）

用官方 mcp 库的 FastMCP（超简单）：

pip install mcp

# my_server.py
from mcp.server.fastmcp import FastMCP

# 创建 server
mcp = FastMCP("我的工具服务")

# 用装饰器定义工具（就像写普通函数）
@mcp.tool()
def add(a: int, b: int) -> int:
    """计算两数之和"""
    return a + b

@mcp.tool()
def get_weather(city: str) -> str:
    """查询城市天气"""
    return f"{city}今天晴，25度"

# 定义资源（可读数据）
@mcp.resource("config://app")
def get_config() -> str:
    """获取应用配置"""
    return "app_name=demo, version=1.0"

# 启动
if __name__ == "__main__":
    mcp.run()        # 默认 stdio 传输

就这样,你写了一个 MCP Server！任何 MCP Host 都能用它。

---

2.7 在代码里连接 MCP Server（Client 侧）

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    # 配置要连接的 server（启动本地子进程）
    server_params = StdioServerParameters(
        command="python",
        args=["my_server.py"],
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()           # 握手初始化

            # 列出 server 提供的工具
            tools = await session.list_tools()
            print("可用工具：", [t.name for t in tools.tools])

            # 调用工具
            result = await session.call_tool("add", {"a": 3, "b": 5})
            print("结果：", result.content[0].text)    # 8

asyncio.run(main())

---

2.8 MCP + 大模型结合（完整闭环）

把 MCP 工具喂给大模型,让模型自己调：

import asyncio, json
from openai import OpenAI
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

client = OpenAI(api_key="sk-xxx")

async def main():
    server_params = StdioServerParameters(command="python", args=["my_server.py"])

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # 1. 把 MCP 工具转成 OpenAI 格式
            mcp_tools = await session.list_tools()
            openai_tools = [{
                "type": "function",
                "function": {
                    "name": t.name,
                    "description": t.description,
                    "parameters": t.inputSchema,
                },
            } for t in mcp_tools.tools]

            # 2. 模型决定调用
            messages = [{"role": "user", "content": "算一下 12 加 30"}]
            response = client.chat.completions.create(
                model="gpt-4o-mini", messages=messages, tools=openai_tools,
            )
            msg = response.choices[0].message

            # 3. 通过 MCP 执行工具
            if msg.tool_calls:
                for tc in msg.tool_calls:
                    args = json.loads(tc.function.arguments)
                    result = await session.call_tool(tc.function.name, args)
                    print("MCP工具结果：", result.content[0].text)

asyncio.run(main())

这就是你 Java 项目做的事的 Python 版：模型 + MCP 工具的完整链路。

---

第三部分：Agent 框架横向对比

3.1 四大框架速览

框架	出品方	特点	适合场景
LangGraph	LangChain	图状态机,可控性强,支持 checkpoint	复杂有状态流程、需要精细控制
OpenAI Agents SDK	OpenAI	轻量,多 agent 交接(handoff)	OpenAI 生态,简洁多agent
CrewAI	CrewAI	角色协作,上手快	多角色分工任务
AutoGen	微软	多agent对话,研究向	多agent讨论、复杂协作

---

3.2 LangGraph（前面讲过,这里对比）

from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

agent = create_react_agent(
    model=ChatOpenAI(model="gpt-4o-mini"),
    tools=[...],
)
result = agent.invoke({"messages": [("human", "查天气")]})

特点：把流程画成"图",每个节点是一步,边是流转。最适合你 Java 项目那种"分析→执行→监督→总结"的多步可控流程。

---

3.3 OpenAI Agents SDK（轻量新秀）

OpenAI 官方的 Agent 框架（Swarm 的正式版）：

pip install openai-agents

from agents import Agent, Runner, function_tool

# 定义工具
@function_tool
def get_weather(city: str) -> str:
    return f"{city}晴，25度"

# 定义 agent
agent = Agent(
    name="助手",
    instructions="你是一个友好的助手",
    tools=[get_weather],
)

# 运行
result = Runner.run_sync(agent, "北京天气怎么样？")
print(result.final_output)

多 Agent 交接（handoff,这框架的特色）：

# 专业 agent
weather_agent = Agent(name="天气专家", instructions="只回答天气问题")
code_agent = Agent(name="编程专家", instructions="只回答编程问题")

# 总控 agent，根据问题转交给专业 agent
triage_agent = Agent(
    name="分诊台",
    instructions="判断问题类型，转给对应专家",
    handoffs=[weather_agent, code_agent],     # 可转交的对象
)

result = Runner.run_sync(triage_agent, "Python怎么读文件？")
# 自动转交给 code_agent 处理

---

3.4 CrewAI（角色协作,小白友好）

把 Agent 想成"员工",组队干活：

pip install crewai

from crewai import Agent, Task, Crew

# 定义角色（像招聘员工）
researcher = Agent(
    role="研究员",
    goal="收集资料",
    backstory="你是资深行业研究员",
)
writer = Agent(
    role="作家",
    goal="写文章",
    backstory="你是专业科技作家",
)

# 定义任务
research_task = Task(
    description="研究AI Agent发展趋势",
    agent=researcher,
)
write_task = Task(
    description="根据研究写一篇文章",
    agent=writer,
)

# 组队执行（团队协作）
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
)
result = crew.kickoff()

特点：拟人化,适合"多角色分工"的任务（如"策划+程序员+测试"协作出软件）。

---

3.5 AutoGen（微软,多 agent 对话）

pip install autogen-agentchat autogen-ext

from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

model_client = OpenAIChatCompletionClient(model="gpt-4o-mini")

# 两个 agent 互相对话解决问题
assistant = AssistantAgent("助手", model_client=model_client)
# AutoGen 擅长让多个 agent 像开会一样讨论

特点：多 agent 像开会讨论,研究和复杂协作场景强。

---

3.6 选型决策树（小白照着选）

你的需求是？
│
├─ 就想简单调个模型、加几个工具
│   → 厂商 SDK（OpenAI SDK）直接写，不用框架
│
├─ 工具想标准化、给多个应用复用
│   → MCP（写成 MCP Server）
│
├─ 多步骤、有状态、要精细控制流程
│   → LangGraph
│
├─ 多个 agent 分工协作
│   → CrewAI（拟人简单）/ AutoGen（复杂讨论）
│
└─ OpenAI 生态、要简洁的多agent交接
    → OpenAI Agents SDK

---

总结：完整知识地图

                    你的学习路径
                         │
    ┌────────────────────┼────────────────────┐
    ▼                    ▼                     ▼
厂商 SDK              MCP 协议             Agent 框架
(内功/原理)          (工具标准)           (招式/封装)
    │                    │                     │
OpenAI SDK          写 MCP Server        LangGraph
Anthropic SDK       连 MCP Client        CrewAI
手写Agent循环        三大能力             AutoGen
    │                Tools/Resources      OpenAI Agents
    │                /Prompts                  │
    └────────────────────┴─────────────────────┘
                         │
                  全部对应你的
                  Java Agent 项目