OpenAI Agents SDK 运行智能体
定义智能体只是准备工作。运行时需要确定一次运行执行什么、下一轮如何继续,以及等待批准或工具工作时如何暂停。
智能体循环
一次SDK运行对应一个应用级轮次。runner持续循环,直到达到实际停止点:
- 使用准备好的输入调用当前智能体的模型。
- 检查模型输出。
- 如果有工具调用,执行工具并继续。
- 如果交接给其他专项智能体,切换智能体并继续。
- 如果生成最终答案且没有后续工具工作,返回结果。
这是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的一致性。