核心概念:从一个客服分诊系统认全部件

1.0贯穿全章的场景:客服分诊

抽象概念悬在空中很难记。整章用一个具体系统做锚:一个客服分诊服务。用户发来一句话(比如"我上个月被多扣了一笔费用"),系统先由一个分诊 agent 判断意图,再把对话交给对应的专家 agent(计费 / 技术),专家查数据、给出回复。

这个小系统恰好用到本章每一个部件。先看它的整体形状,后面每节再把其中一块拆开讲透。

1.1Chat Client:模型连接器

把"对话请求"翻译成某个 LLM provider 的 API 调用,并把响应翻回框架统一的消息类型。

底层机制(比文档深一层):Chat Client 不只是 HTTP 封装。它实现一个统一的 chat 接口——输入是 messages + tools + options,输出是带或不带 tool-call 的 response——并把 provider 特有的能力(流式、structured output、function-calling 的报文格式)适配成框架的统一表示。.create_agent(...) 是工厂方法:它把"模型连接"与"agent 的指令 / 工具"绑在一起,产出一个 ChatAgent。换句话说,Chat Client 自身是无状态的纯连接器,带指令的执行单元是它造出来的 Agent。

# 说明性示例,展示概念形状,未在本机运行
from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient(model_id="gpt-4.1")   # 纯连接器,无状态
triage = client.create_agent(                   # 工厂方法:连接 + 指令 -> Agent
    name="triage",
    instructions="判断用户意图:billing 还是 technical。",
)

与下一个概念的关系:Chat Client 产出的那个东西——Agent——才是本章的主角,也是第一个门槛。

1.2Agent / ChatAgent:无状态执行单元

一个带指令和工具的 LLM 执行单元;它本身不记对话,每次 run 都要喂入会话状态。

底层机制(比文档深一层):run() 内部跑一个循环。把(指令 + thread 历史 + 本次输入)发给模型;若模型返回 tool calls,框架逐个 dispatch 到你的函数,把工具结果作为新消息追加;再发给模型;直到模型返回不带 tool call 的最终答复。两个后端工程师必须记住的点:

• 默认是多轮工具循环(multi-turn)。不像 AutoGen v0.2 的单轮——一次 run() 往返模型的次数不定,取决于模型要调几轮工具。成本和延迟容易超出"一次问答"的直觉。
• Agent 对象不持有这个循环产生的历史。历史进 thread,不进 agent。

与下一个概念的关系:Agent 的"手"是工具——它怎么知道有哪些工具可调、又怎么把模型的请求接到你的 Python 函数上?

1.3Tools / @ai_function:把函数交给模型

用装饰器把普通函数暴露给模型;框架从类型注解自动生成 JSON schema。

底层机制(比文档深一层):装饰器在注册时反射函数签名(参数名、类型注解、默认值)和 docstring,生成符合 provider function-calling 格式的 schema。运行时模型返回一个 tool call(函数名 + JSON 参数),框架按名查表、把 JSON 反序列化成 Python 参数、调用你的函数、把返回值序列化回消息塞进循环。结论:类型注解不是装饰——它直接决定模型看到的参数类型,注解写错或缺失,模型就更容易传错类型的参数。

from agent_framework import ai_function

@ai_function
def lookup_invoice(invoice_id: str) -> str:
    """按发票号查询金额与状态。"""   # docstring 进入 schema 的 description
    ...                              # invoice_id 的类型注解 -> schema 的参数类型

billing = client.create_agent(
    name="billing",
    instructions="处理计费问题,必要时查发票。",
    tools=[lookup_invoice],          # 工具装配到 agent 上
)

与下一个概念的关系:Agent 无状态(§1.2),工具是它的手,那"记住上一句话"这件事到底落在哪个对象上?

1.4AgentThread:显式的会话状态

显式的会话状态对象——保存一段对话的消息历史,跨多次 run 传递,可序列化、可换存储后端。

底层机制(比文档深一层):Thread 有两种持久化模型,这是设计核心,不是实现细节:

这两条决定了三件大事:能不能水平扩展、对话能不能跨进程恢复、谁为历史存储付费。还有个硬约束:server-backed 的 agent 禁止本地历史——thread 退化成一个纯远端指针,持久化策略由 chat client 决定,你没得选。

thread = triage.get_new_thread()             # 显式创建会话状态
await triage.run("我被多扣了一笔钱", thread=thread)   # 第 1 轮
await triage.run("就上个月那笔", thread=thread)        # 第 2 轮,带着同一个 thread -> 记得上一句

与下一个概念的关系:日志、鉴权、PII 脱敏这些横切关注点,不该散进每个工具里——它们落在 middleware 这一层。

1.5Middleware:包在调用外面的洋葱层

可链式的处理器,包住 agent run 和函数调用,集中处理日志、鉴权、限流、护栏。

底层机制(比文档深一层):两类 middleware——function middleware(包每次工具调用)和 chat / agent middleware(包每次 agent run 或模型调用)。结构是洋葱模型:请求逐层向内穿到核心(模型 / 工具),响应再逐层向外穿回。每层都能读改请求、短路直接返回、记录耗时。于是护栏可以在请求进模型前拦截(脱敏 PII),也可以在工具结果回来后过滤敏感字段。这一套是 Semantic Kernel 带进 MAF 的企业基因。

与下一个概念的关系:单个 agent 的四个部件(连模型、连工具、连历史、连横切)齐了。把多个 agent 编起来——这里 MAF 露出第二个门槛:编排有两副面孔。

1.6两套编排面:AgentChat 模式 与 Workflow 图引擎

MAF 提供两种把多个 agent 组织起来的方式:轻量对话式的 AgentChat 模式,与显式图式的 Workflow。

底层机制(比文档深一层):

• AgentChat 模式:用 builder 把一组 agent 组织成 Sequential(顺序传递)、Concurrent(并行扇出再聚合)、Handoff(一个 agent 把控制权交给另一个)、GroupChat(多 agent 轮流发言)、Magentic(一个 LLM manager 动态规划)。重心是"agent 之间传消息",轻量、偏非确定。分诊场景里"分诊 → 交给专家"就是一次 handoff。
• Workflow 图引擎:用 WorkflowBuilder 把 Executor(工作单元,可以包一个 agent)用 Edge(带类型、带条件)连成有向图,按 Pregel 超步推进,支持检查点、共享状态、人工介入(HITL)。重心是"数据在图里流动 + 可恢复"。

1.7协议与可观测:MCP / A2A / OpenTelemetry

最后三个部件,分量轻些,但要知道它们在图上的位置:

• MCP(Model Context Protocol,已 GA):让 agent 通过 MCP server 发现并调用外部工具。把"工具"从你进程内的 @ai_function 扩展到任何 MCP 服务暴露的工具。机制上,agent 多了一个"远程工具来源",调用链和本地工具一样进 agentic loop。
• A2A(Agent-to-Agent,preview):agent 之间互操作的协议。截至 2026-06,MAF 的 A2A 绑定仍是 preview("即将支持 1.0")。能用来连别家的 agent,但别当生产依赖。
• OpenTelemetry:MAF 按 OpenTelemetry 的 GenAI 语义约定发出 traces / logs / metrics。这是 SK 带进来的可观测基因——agent 的调用链能直接接进现有 APM,不必另造一套监控。