codecamp

OpenAI Agents SDK 运行智能体

定义智能体只是准备工作。运行时需要确定一次运行执行什么、下一轮如何继续,以及等待批准或工具工作时如何暂停。

智能体循环

一次SDK运行对应一个应用级轮次。runner持续循环,直到达到实际停止点:

  1. 使用准备好的输入调用当前智能体的模型。
  2. 检查模型输出。
  3. 如果有工具调用,执行工具并继续。
  4. 如果交接给其他专项智能体,切换智能体并继续。
  5. 如果生成最终答案且没有后续工具工作,返回结果。

这是SDK的核心概念。工具、交接、批准和流式都建立在同一循环之上。

为对话选择一种策略

状态带入下一轮的常见方式有四种:

策略 状态位置 适用场景 下一轮传入内容
TypeScript的result.history或Python的result.to_input_list() 应用 简单聊天循环,或希望最大程度控制 可重放的历史
session 自有存储与SDK 持久聊天状态、可恢复运行、自管存储 同一个会话
conversationId OpenAI Conversations API 多个工作进程或服务共享服务端状态 同一个对话ID及新一轮输入
TypeScript的previousResponseId或Python的previous_response_id OpenAI Responses API 最轻量的服务端逐响应继续 上一次响应ID及新一轮输入

多数应用应为每段对话选定一种策略。混用本地历史重放与服务端状态可能重复上下文,除非有意协调两个状态层。

以下通过会话持久保存多轮状态:

来源示例 1(javascript):

// [中文] 示例1:为对话选择一种策略。
// [中文] 旅行向导简短回答:先问“金门大桥在哪座城市”,再问“它在哪个州”;两轮复用同一个SDK会话。
// [中文] JavaScript示例使用MemorySession,Python使用SQLiteSession;不能把内存会话描述为已经写入持久数据库。
import { Agent, MemorySession, run } from "@openai/agents";

const agent = new Agent({
  name: "Tour guide",
  instructions: "Answer with compact travel facts.",
});

const session = new MemorySession();

const firstTurn = await run(agent, "What city is the Golden Gate Bridge in?", {
  session,
});
console.log(firstTurn.finalOutput);

const secondTurn = await run(agent, "What state is it in?", { session });
console.log(secondTurn.finalOutput);

来源示例 2(python):

## [中文] 示例2:为对话选择一种策略。
## [中文] 旅行向导简短回答:先问“金门大桥在哪座城市”,再问“它在哪个州”;两轮复用同一个SDK会话。
## [中文] JavaScript示例使用MemorySession,Python使用SQLiteSession;不能把内存会话描述为已经写入持久数据库。
import asyncio

from agents import Agent, Runner, SQLiteSession

agent = Agent(
    name="Tour guide",
    instructions="Answer with compact travel facts.",
)

session = SQLiteSession("conversation_123")


async def main() -> None:
    first_turn = await Runner.run(
        agent,
        "What city is the Golden Gate Bridge in?",
        session=session,
    )
    print(first_turn.final_output)

    second_turn = await Runner.run(
        agent,
        "What state is it in?",
        session=session,
    )
    print(second_turn.final_output)


if __name__ == "__main__":
    asyncio.run(main())

希望有持久记忆、可恢复批准流程或应用控制的存储时,会话通常是合适的默认方案。

以下使用服务端管理的状态继续:

来源示例 3(javascript):

// [中文] 示例3:为对话选择一种策略。
// [中文] 指令要求非常简洁地回答;两轮依次询问金门大桥所在城市和州,只为后续轮次发送新输入。
// [中文] JavaScript创建并复用conversationId;Python复用first.last_response_id形成响应链,这是两种不同的服务端继续方式。
import { Agent, run } from "@openai/agents";
import OpenAI from "openai";

const agent = new Agent({
  name: "Assistant",
  instructions: "Reply very concisely.",
});

const client = new OpenAI();
const { id: conversationId } = await client.conversations.create({});

const first = await run(agent, "What city is the Golden Gate Bridge in?", {
  conversationId,
});
console.log(first.finalOutput);

const second = await run(agent, "What state is it in?", {
  conversationId,
});
console.log(second.finalOutput);

来源示例 4(python):

## [中文] 示例4:为对话选择一种策略。
## [中文] 指令要求非常简洁地回答;两轮依次询问金门大桥所在城市和州,只为后续轮次发送新输入。
## [中文] JavaScript创建并复用conversationId;Python复用first.last_response_id形成响应链,这是两种不同的服务端继续方式。
import asyncio

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="Reply very concisely.",
)


async def main() -> None:
    first = await Runner.run(
        agent,
        "What city is the Golden Gate Bridge in?",
    )
    print(first.final_output)

    second = await Runner.run(
        agent,
        "What state is it in?",
        previous_response_id=first.last_response_id,
    )
    print(second.final_output)


if __name__ == "__main__":
    asyncio.run(main())

多个系统共享同一个具名对话时,使用conversationId;希望通过上一次响应ID逐响应继续时,使用TypeScript的previousResponseId或Python的previous_response_id。复用响应ID不表示历史输入词元免费,计费说明见对话状态指南。

增量流式运行

流式使用相同循环和状态策略,差别在于运行尚未结束时即可消费事件:

来源示例 5(javascript):

// [中文] 示例5:增量流式运行。
// [中文] 行星向导以简短事实回答“给出土星的三个简短事实”;只打印相应文字增量,再打印最终结果。
// [中文] JavaScript等待stream.completed;Python消费stream_events迭代器。两种语言的事件类型不同,原样保留。
import { Agent, run } from "@openai/agents";

const agent = new Agent({
  name: "Planet guide",
  instructions: "Answer with short facts.",
});

const stream = await run(agent, "Give me three short facts about Saturn.", {
  stream: true,
});

for await (const event of stream) {
  if (
    event.type === "raw_model_stream_event" &&
    event.data.type === "output_text_delta"
  ) {
    process.stdout.write(event.data.delta);
  }
}

await stream.completed;
console.log("\nFinal:", stream.finalOutput);

来源示例 6(python):

## [中文] 示例6:增量流式运行。
## [中文] 行星向导以简短事实回答“给出土星的三个简短事实”;只打印相应文字增量,再打印最终结果。
## [中文] JavaScript等待stream.completed;Python消费stream_events迭代器。两种语言的事件类型不同,原样保留。
import asyncio

from openai.types.responses import ResponseTextDeltaEvent

from agents import Agent, Runner

agent = Agent(
    name="Planet guide",
    instructions="Answer with short facts.",
)


async def main() -> None:
    stream = Runner.run_streamed(
        agent,
        "Give me three short facts about Saturn.",
    )

    async for event in stream.stream_events():
        if event.type == "raw_response_event" and isinstance(
            event.data, ResponseTextDeltaEvent
        ):
            print(event.data.delta, end="", flush=True)

    print(f"\nFinal: {stream.final_output}")


if __name__ == "__main__":
    asyncio.run(main())

注意三点:先等流结束,再把运行视为已经稳定结束;因批准暂停时,处理interruptions并从state恢复,不新开用户轮次;中途取消流后,若要之后继续同一轮次,应从state恢复未完成部分。

有意识地处理暂停与失败

非正常完成的结果主要分两类:一类是运行时或验证失败,例如达到最大轮次、护栏异常或工具错误;另一类是预期暂停,例如人工批准请求,此时有意中断,之后从相同状态恢复。

应把批准视为暂停运行,而非新轮次,才能保持轮次计数、历史和服务端继续ID的一致性。

后续步骤

OpenAI Agents SDK 结果与状态
OpenAI Agents SDK 沙箱智能体
温馨提示
下载编程狮App,免费阅读超1000+编程语言教程
取消
确定
目录

其他能力与进阶指南

Embeddings 接口参考

审计日志接口参考

关闭

MIP.setData({ 'pageTheme' : getCookie('pageTheme') || {'day':true, 'night':false}, 'pageFontSize' : getCookie('pageFontSize') || 20 }); MIP.watch('pageTheme', function(newValue){ setCookie('pageTheme', JSON.stringify(newValue)) }); MIP.watch('pageFontSize', function(newValue){ setCookie('pageFontSize', newValue) }); function setCookie(name, value){ var days = 1; var exp = new Date(); exp.setTime(exp.getTime() + days*24*60*60*1000); document.cookie = name + '=' + value + ';expires=' + exp.toUTCString(); } function getCookie(name){ var reg = new RegExp('(^| )' + name + '=([^;]*)(;|$)'); return document.cookie.match(reg) ? JSON.parse(document.cookie.match(reg)[2]) : null; }