AI Agent 入门教程：01-基础概念、例子与技术背景

先运行一次模型调用

创建虚拟环境，安装 OpenAI Python SDK，并通过环境变量提供模型名和 API Key。代码只做一次请求，没有工具，也没有循环。

import os
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model=os.environ["OPENAI_MODEL"],
    input="用三句话说明 AI Agent 与普通聊天机器人的差别。",
)

print(response.output_text)

运行时可以观察三项数据：用户输入、模型输出、程序是否还会继续。此处程序打印文本后结束，下一步完全没有发生。

用户输入 ──▶ 模型 ──▶ 文本输出 ──▶ 程序结束

这是一条 Chat 路径。模型生成了内容，程序没有让它改变控制流。

三种控制方式放在一起看

同一个“技术简报”需求可以写成三种程序。

Workflow 并不比 Agent 落后。固定流程通常更便宜，也更容易测试。只有当中间观察会改变行动，而且代码难以枚举所有路径时，才需要让模型参与决策。

Agent Loop 里有哪些角色

把 Agent 缩到最小，只剩五个位置。

                 ┌───────────────┐
                 │   任务目标     │
                 └───────┬───────┘
                         ▼
┌──────────┐      ┌───────────────┐      ┌──────────┐
│ 环境结果  │ ───▶ │ 模型选择行动   │ ───▶ │ 工具执行  │
└────▲─────┘      └───────┬───────┘      └────┬─────┘
     │                    │                    │
     └────────────────────┘◀───────────────────┘
                          │
                          ▼
                    满足停止条件

• 目标规定要完成什么。
• 观察包含用户输入、工具结果和错误。
• 决策由模型从允许行动中选择。
• 工具接触文件、数据库或外部 API。
• 停止条件由应用检查成功、失败和预算耗尽。

模型只占图中的一个框。权限、工具实现、状态保存和退出条件都属于应用代码。

用三个需求练习边界判断

第一个需求是把会议记录改写成邮件。输入已经完整，一次调用足够，选择 Chat。

第二个需求是收到工单后先分类，再按固定规则分配团队。类别有限，分支能写进代码，选择 Workflow。

第三个需求是调查某个新框架。第一次搜索可能没有官方资料，也可能发现版本冲突，需要根据证据决定补查、换关键词或结束。这个任务具备 Agent Loop 的条件。

判断时写下三行：允许行动有哪些、什么观察会改变下一步、程序凭什么结束。三行写不出来，需求还没有清楚到可以开始开发。

从一次模型调用到 Agent Loop

一次模型调用和一张边界图还构不成 Agent。图中的关系会贯穿后面的代码：模型生成决策，应用约束决策，工具改变环境，停止条件关闭循环。

这套循环建立在 LLM、结构化输出和 Function Calling 之上。下面沿着技术演进，拆开模型、工具与 Agent Runtime 各自承担的工作。

LLM 最初只负责预测下一段文本

大语言模型接收一段 token，生成下一段 token。一次聊天请求可以改写、摘要、分类和回答知识问题，但模型本身不会打开文件、查询数据库，也不知道生成文本之后程序做了什么。

Prompt ──▶ LLM ──▶ Tokens

早期应用通过解析自然语言约定动作，例如让模型输出 SEARCH: agent loop。这种格式容易漂移，也会把字符串解析逻辑散进业务代码。

结构化输出让模型能表达“行动请求”

JSON Schema 给输出加上字段和类型。Function Calling 进一步把可用函数的名称、描述和参数 Schema 交给模型，模型可以返回结构化调用。

用户问题 + 工具 Schema
          │
          ▼
         LLM
          │
          ├──▶ 最终文本
          └──▶ function_call(name, arguments)

function_call 仍然是模型输出。应用检查工具白名单和参数后，才执行真实函数。模型没有因此获得服务器权限。

工具把模型接到外部环境

工具可以读取文件、搜索资料、查询数据库、调用业务 API 或创建副作用。工具结果回到模型后，模型获得新的观察，再决定下一步。

LLM 决策 ──▶ Tool 执行 ──▶ 环境变化 / 数据结果
   ▲                              │
   └──────────────────────────────┘

这个回路让系统从一次生成变成多步任务。工具数量增加后，还需要 Schema、权限、超时、重试、结果上限和审计。

上下文窗口承担短期工作区

模型每轮只能看到当前请求携带的内容。用户目标、历史消息、工具结果和检索证据都要装进上下文窗口。窗口有限，信息还具有不同优先级和信任等级。

RAG 解决资料召回，Context Engineering 负责选择、排列、压缩和标记。Session 可以续接线程，Checkpoint 则保存应用控制状态。它们会在第三阶段分别实现。

Agent Runtime 管理循环和边界

模型 API 没有自动提供完整 Agent 系统。运行时至少要处理：

• 把当前状态发给模型。
• 解析最终文本、工具调用或控制转移。
• 执行允许的工具并记录结果。
• 检查轮数、费用、时间与权限。
• 保存状态、暂停审批、恢复任务。
• 记录 Trace 并交给评测器验收。

┌──────────────── Agent Runtime ────────────────┐
│  State ─▶ Model ─▶ Decision ─▶ Tool ─▶ State │
│    │                                   │      │
│    └──── Budget / Permission / Trace ──┘      │
└───────────────────────────────────────────────┘

OpenAI Agents SDK、LangGraph 等框架提供不同层次的运行时抽象。后面的代码会先手写一个小型运行时，再迁移到框架，用实现对照每个抽象。

技术演进怎样改变应用能力

第 2 篇把这张 Agent Loop 图放进典型场景，并确定 brief-agent 的输入、输出、工具白名单和禁止项。