Appearance
OpenAI AgentKit 完整指导手册
学习如何使用 AgentKit 构建、部署和优化智能体工作流。智能体是能够智能地完成任务的系统——从简单目标到复杂的开放式工作流。OpenAI 提供具有智能体能力的模型、用于智能体创建和部署的工具包,以及用于监控和优化智能体的仪表板功能。
AgentKit
AgentKit 是一个用于构建、部署和优化智能体的模块化工具包。
核心模块
| 模块 | 功能 |
|---|---|
| 构建 | 使用 Agent Builder 创建工作流,这是一个带有入门模板的可视化画布 |
| 部署 | 使用 ChatKit 将你的智能体工作流嵌入到前端 |
| 优化 | 构建强大的评估系统来观察和改进智能体性能 |
如何构建智能体
构建智能体是一个设计工作流并连接 OpenAI 平台各个组件以满足你目标的过程。Agent Builder 将所有这些基础要素整合到一个用户界面中。
| 目标 | 使用什么 | 描述 |
|---|---|---|
| 构建智能体工作流 | Agent Builder | 用于创建智能体工作流的可视化画布。将模型、工具、知识和逻辑全部整合在一起。 |
| 连接到大语言模型 | OpenAI 模型 | 能够推理、做决策和处理数据的核心智能。在 Agent Builder 中选择你的模型。 |
| 为智能体配备能力 | 工具、护栏 | 通过连接器和 MCP 访问第三方服务,搜索向量存储,并防止滥用。 |
| 提供知识和记忆 | 向量存储、文件搜索、嵌入 | 由 OpenAI 托管的外部和持久知识,为你的用例提供更相关的信息。 |
| 添加控制流逻辑 | 逻辑节点 | 自定义智能体如何协同工作、处理条件和路由到其他智能体的逻辑。 |
| 编写自己的代码 | Agents SDK | 构建智能体应用程序,使用工具和编排,而不是使用 Agent Builder 作为后端。 |
注意
Agent Builder 暂时不支持语音智能体。
在你的产品中部署智能体
当你准备将智能体投入生产时,使用 ChatKit 将智能体工作流引入你的产品 UI,通过与智能体后端连接的可嵌入聊天。
| 目标 | 使用什么 | 描述 |
|---|---|---|
| 嵌入你的智能体 | ChatKit | 可自定义的 UI 组件。粘贴你的工作流 ID 以将智能体工作流嵌入到你的产品中。 |
| 获得更多自定义 | 高级 ChatKit | 在你自己的基础设施上运行 ChatKit。使用小部件并通过 SDK 连接到任何智能体后端。 |
优化智能体性能
使用 OpenAI 平台评估智能体性能并自动化改进。
| 目标 | 使用什么 | 描述 |
|---|---|---|
| 评估智能体性能 | 评估功能 | 完整的评估平台,包括对外部模型评估的支持。 |
| 自动化追踪评分 | 追踪评分 | 开发、部署、监控和改进智能体。 |
| 构建和跟踪评估 | 数据集 | 在测试环境中构建智能体级评估的协作界面。 |
| 优化提示词 | 提示词优化器 | 测量智能体性能,识别改进领域,并优化你的智能体。 |
Agent Builder
在 playground 中可视化组装、调试和导出多步骤智能体工作流。
Agent Builder 是一个用于构建多步骤智能体工作流的可视化画布。
你可以从模板开始,为工作流中的每个步骤拖放节点,提供类型化的输入和输出,并使用实时数据预览运行。当你准备部署时,使用 ChatKit 将工作流嵌入到你的网站中,或下载 SDK 代码自行运行。
使用本指南了解构建智能体的过程和组成部分。
智能体和工作流
要构建有用的智能体,你需要为它们创建工作流。工作流是智能体、工具和控制流逻辑的组合。工作流封装了处理任务或支持聊天所涉及的所有步骤和操作,提供准备就绪可部署的工作代码。
构建智能体来处理任务有三个主要步骤:
- 在 Agent Builder 中设计工作流。这定义了你的智能体及其工作方式。
- 发布你的工作流。它是一个带有 ID 和版本控制的对象。
- 部署你的工作流。将 ID 传递到你的 ChatKit 集成中,或下载 Agents SDK 代码自行部署工作流。
使用节点组合
在 Agent Builder 中,插入并连接节点以创建你的工作流。节点之间的每个连接都成为类型化边。单击节点以配置其输入和输出,观察步骤之间的数据契约,并确保下游节点接收到它们期望的属性。
示例和模板
Agent Builder 提供常见工作流模式的模板。从模板开始可以了解节点如何协同工作,或从头开始创建。
这是一个作业辅导工作流。它使用智能体接收问题,重新表述以获得更好的答案,将它们路由到其他专业智能体,并返回答案。
可用节点
节点是智能体的构建块。要查看所有可用节点及其配置选项,请参阅以下"节点参考"。
预览和调试
在构建过程中,你可以使用预览功能测试工作流。在这里,你可以交互式地运行工作流,附加示例文件,并观察每个节点的执行。
评估你的工作流
在 Agent Builder 内部运行追踪评分器。在顶部导航中,点击评估。在这里,你可以选择一个追踪(或一组追踪)并运行自定义评分器来评估整体工作流性能。
发布你的工作流
Agent Builder 会在你工作时自动保存。当你对工作流满意时,发布它以创建一个新的主要版本作为快照。然后你可以在 ChatKit(OpenAI 的嵌入式聊天体验框架)中使用你的工作流。
你可以创建新版本或在 API 调用中指定旧版本。
在你的产品中部署
当你准备实施创建的智能体工作流时,点击顶部导航中的代码。你有两个选项在生产环境中实施工作流:
ChatKit:按照ChatKit章节指导,传入你的工作流 ID,将此工作流嵌入到你的应用程序中。
高级集成:复制工作流代码并在任何地方使用。你可以在自己的基础设施上运行 ChatKit,并使用 Agents SDK 构建和自定义智能体聊天体验。
节点参考
Agent Builder 是一个用于组合智能体工作流的可视化画布。工作流由控制顺序和流程的节点和连接组成。插入节点,然后配置和连接它们以定义你希望智能体遵循的过程。
核心节点
从基本构建块开始。所有工作流都有开始和智能体节点。
开始
定义工作流的输入。对于聊天工作流中的用户输入,开始节点做两件事:
- 将用户输入附加到对话历史
- 公开
input_as_text来表示此输入的文本内容
所有聊天开始节点都有 input_as_text 作为输入变量。你也可以添加状态变量。
智能体
定义指令、工具和模型配置,或附加评估。
保持每个智能体的范围明确定义。在我们的作业辅导示例中,我们使用一个智能体重写用户的查询以提高知识库的特定性和相关性。我们使用另一个智能体将查询分类为问答或事实查找,并使用另一个智能体处理每种类型的问题。
像使用任何其他模型提示词一样添加模型行为指令和用户消息。要从前一步骤传递输出,你可以将其添加为上下文。
你可以拥有任意多个智能体节点。
注释
留下关于工作流的评论和解释。与其他节点不同,注释在流程中不执行任何操作。它们只是为你和你的团队提供有用的注释。
工具节点
工具节点让你为智能体配备工具和外部服务。你可以检索数据、监控滥用并连接到外部服务。
文件搜索
从你在 OpenAI 平台中创建的向量存储中检索数据。通过向量存储 ID 进行搜索,并为模型应该搜索的内容添加查询。你可以使用变量在查询中包含工作流中前面节点的输出。
要在 OpenAI 托管存储之外搜索,请改用 MCP。
MCP
调用第三方工具和服务。使用 OpenAI 连接器或第三方服务器进行连接,或添加你自己的服务器。MCP 连接在需要读取或搜索其他应用程序(如 Gmail 或 Zapier)中的数据的工作流中很有用。
逻辑节点
逻辑节点让你编写自定义逻辑并定义控制流——例如,基于自定义条件循环,或在继续操作之前要求用户批准。
If/else
添加条件逻辑。使用通用表达式语言 (CEL) 创建自定义表达式。用于定义如何处理已分类的输入。
例如,如果智能体将输入分类为问答,则将该查询路由到问答智能体以获得直接答案。如果是开放式查询,则路由到查找相关事实的智能体。否则,结束工作流。
While
基于自定义条件循环。使用通用表达式语言 (CEL) 创建自定义表达式。用于检查条件是否仍然为真。
人工批准
将决策权交给最终用户进行批准。对于智能体起草工作但在发出之前可能需要人工审查的工作流很有用。
例如,想象一个代表你发送电子邮件的智能体工作流。你将包含一个输出电子邮件小部件的智能体节点,然后紧跟一个人工批准节点。你可以配置人工批准节点询问"你想让我发送这封电子邮件吗?",如果批准,则继续到连接到 Gmail 的 MCP 节点。
数据节点
数据节点让你在工作流中定义和操作数据。重塑输出或定义在整个工作流中使用的全局变量。
转换
重塑输出(例如,对象 → 数组)。用于强制类型遵守你的模式或重塑输出以便智能体读取和理解作为输入。
设置状态
定义在整个工作流中使用的全局变量。当智能体接收输入并输出你希望在整个工作流中使用的新内容时很有用。你可以将该输出定义为新的全局变量。
ChatKit
使用 ChatKit 构建和自定义可嵌入的聊天。
ChatKit 是构建智能体聊天体验的最佳方式。无论你是构建内部知识库助手、人力资源入职帮手、研究伙伴、购物或日程安排助手、故障排除机器人、财务规划顾问还是支持智能体,ChatKit 都提供可自定义的聊天嵌入来处理所有用户体验细节。
使用 ChatKit 的可嵌入 UI 小部件、可自定义的提示词、工具调用支持、文件附件和思维链可视化来构建智能体,而无需重新发明聊天 UI。
概述
有两种方式实施 ChatKit:
- 推荐集成。在前端嵌入 ChatKit,自定义其外观和感觉,让 OpenAI 从 Agent Builder 托管和扩展后端。需要开发服务器。
- 高级集成。在你自己的基础设施上运行 ChatKit。使用 ChatKit Python SDK 并连接到任何智能体后端。使用小部件构建前端。
ChatKit 入门
| 方案 | 描述 |
|---|---|
| 在前端嵌入 ChatKit | 嵌入聊天小部件,自定义其外观和感觉,让 OpenAI 托管和扩展后端 |
| 高级集成 | 使用任何后端和 ChatKit SDK 构建你自己的自定义 ChatKit 用户体验 |
在前端嵌入 ChatKit
在高层次上,设置 ChatKit 是一个三步过程。创建一个托管在 OpenAI 服务器上的智能体工作流。然后设置 ChatKit 并添加功能来构建你的聊天体验。
1. 创建智能体工作流
使用 Agent Builder 创建智能体工作流。Agent Builder 是一个用于设计多步骤智能体工作流的可视化画布。你将获得一个工作流 ID。
嵌入在前端的聊天将指向你创建的工作流作为后端。
2. 在你的产品中设置 ChatKit
要设置 ChatKit,你将创建一个 ChatKit 会话并创建一个后端端点,传入你的工作流 ID,交换客户端密钥,添加一个脚本以在你的网站上嵌入 ChatKit。
步骤 1:在你的服务器上,生成客户端令牌
此代码片段启动一个 FastAPI 服务,其唯一工作是通过 OpenAI Python SDK 创建一个新的 ChatKit 会话并返回会话的客户端密钥:
python
from fastapi import FastAPI
from pydantic import BaseModel
from openai import OpenAI
import os
app = FastAPI()
openai = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
@app.post("/api/chatkit/session")
def create_chatkit_session():
session = openai.chatkit.sessions.create({
# ...
})
return { client_secret: session.client_secret }步骤 2:在你的服务器端代码中,将你的工作流 ID 和密钥传递到会话端点
客户端密钥是你的 ChatKit 前端用于打开或刷新聊天会话的凭据。你不存储它;你立即将其传递给 ChatKit 客户端库。
typescript
export default async function getChatKitSessionToken(
deviceId: string
): Promise<string> {
const response = await fetch("https://api.openai.com/v1/chatkit/sessions", {
method: "POST",
headers: {
"Content-Type": "application/json",
"OpenAI-Beta": "chatkit_beta=v1",
Authorization: "Bearer " + process.env.VITE_OPENAI_API_SECRET_KEY,
},
body: JSON.stringify({
workflow: { id: "wf_68df4b13b3588190a09d19288d4610ec0df388c3983f58d1" },
user: deviceId,
}),
});
const { client_secret } = await response.json();
return client_secret;
}步骤 3:安装 ChatKit React 绑定
bash
npm install @openai/chatkit-react步骤 4:添加 ChatKit JS 脚本到你的页面
html
<script
src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"
async
></script>步骤 5:在你的 UI 中渲染 ChatKit
javascript
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function MyChat() {
const { control } = useChatKit({
api: {
async getClientSecret(existing) {
if (existing) {
// implement session refresh
}
const res = await fetch('/api/chatkit/session', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
});
const { client_secret } = await res.json();
return client_secret;
},
},
});
return <ChatKit control={control} className="h-[600px] w-[320px]" />;
}3. 构建和迭代
参阅以下 自定义主题 章节以了解关于 ChatKit 工作原理的信息。
ChatKit 中的主题和自定义
配置颜色、排版、密度和组件变体。通过浅色和深色主题、设置强调色、控制密度和圆角来匹配你应用的美学。
概述
在高层次上,通过传入一个选项对象来自定义主题。如果你在前端嵌入 ChatKit,请使用下面的 React 语法。
- React:将选项传递给
useChatKit({...}) - 高级集成:使用
chatkit.setOptions({...})设置选项
在两种集成类型中,选项对象的形状是相同的。
更改主题
通过指定颜色、排版等来匹配产品的外观和感觉。下面,我们设置为深色模式,更改颜色,圆角,调整信息密度并设置字体。
jsx
const options: Partial<ChatKitOptions> = {
theme: {
colorScheme: "dark",
color: {
accent: {
primary: "#2D8CFF",
level: 2
}
},
radius: "round",
density: "compact",
typography: { fontFamily: "'Inter', sans-serif" },
},
};自定义开始屏幕文本
通过更改输入框的占位符文本让用户知道要问什么或引导他们的第一次输入。
jsx
const options: Partial<ChatKitOptions> = {
composer: {
placeholder: "询问关于你数据的任何问题...",
},
startScreen: {
greeting: "欢迎使用 FeedbackBot!",
},
};为新线程显示启动提示词
通过建议提示词想法来指导用户在开始对话时要问什么或做什么。
javascript
const options: Partial<ChatKitOptions> = {
startScreen: {
greeting: "今天我能帮你构建什么?",
prompts: [
{
name: "检查工单状态",
prompt: "你能帮我检查工单的状态吗?",
icon: "search"
},
{
name: "创建工单",
prompt: "你能帮我创建一个新的支持工单吗?",
icon: "write"
},
],
},
};启用文件附件
附件默认处于禁用状态。要启用它们,请添加附件配置。除非你使用自定义后端,否则必须使用 hosted 上传策略。
jsx
const options: Partial<ChatKitOptions> = {
composer: {
attachments: {
uploadStrategy: { type: 'hosted' },
maxSize: 20 * 1024 * 1024, // 每个文件 20MB
maxCount: 3,
accept: { "application/pdf": [".pdf"], "image/*": [".png", ".jpg"] },
},
},
}在输入框中使用实体标签启用 @提及
让用户使用 @提及标记自定义"实体"。这可以实现更丰富的对话上下文和交互性。
jsx
const options: Partial<ChatKitOptions> = {
entities: {
async onTagSearch(query) {
return [
{
id: "user_123",
title: "Jane Doe",
group: "People",
interactive: true,
},
{
id: "document_123",
title: "Quarterly Plan",
group: "Documents",
interactive: true,
},
]
},
onClick: (entity) => {
navigateToEntity(entity.id);
},
},
};ChatKit 高级集成
在 ChatKit 中使用你自己的基础设施以获得更多自定义。
当你需要完全控制——自定义身份验证、数据驻留、本地部署或定制智能体编排时——你可以在自己的基础设施上运行 ChatKit。使用 OpenAI 的高级自托管选项来使用你自己的服务器和自定义的 ChatKit。
在你自己的基础设施上运行 ChatKit
在高层次上,高级 ChatKit 集成是构建你自己的 ChatKit 服务器并添加小部件来构建聊天界面的过程。你将使用 OpenAI API 和你的 ChatKit 服务器来构建由 OpenAI 模型驱动的自定义聊天。
设置你的 ChatKit 服务器
按照 GitHub 上的服务器指南了解如何处理传入请求、运行工具并将结果流式传输回客户端。
1. 安装服务器包
bash
pip install openai-chatkit2. 实现服务器类
ChatKitServer 驱动对话。覆盖 respond 以在用户消息或客户端工具输出到达时流式传输事件。
python
class MyChatKitServer(ChatKitServer):
def __init__(self, data_store: Store, file_store: FileStore | None = None):
super().__init__(data_store, file_store)
assistant_agent = Agent[AgentContext](
model="gpt-4.1",
name="Assistant",
instructions="You are a helpful assistant",
)
async def respond(
self,
thread: ThreadMetadata,
input: UserMessageItem | ClientToolCallOutputItem,
context: Any,
) -> AsyncIterator[Event]:
agent_context = AgentContext(
thread=thread,
store=self.store,
request_context=context,
)
result = Runner.run_streamed(
self.assistant_agent,
await to_input_item(input, self.to_message_content),
context=agent_context,
)
async for event in stream_agent_response(agent_context, result):
yield event
async def to_message_content(
self, input: FilePart | ImagePart
) -> ResponseInputContentParam:
raise NotImplementedError()3. 暴露端点
python
app = FastAPI()
data_store = SQLiteStore()
file_store = DiskFileStore(data_store)
server = MyChatKitServer(data_store, file_store)
@app.post("/chatkit")
async def chatkit_endpoint(request: Request):
result = await server.process(await request.body(), {})
if isinstance(result, StreamingResult):
return StreamingResponse(result, media_type="text/event-stream")
return Response(content=result.json, media_type="application/json")4. 建立数据存储契约
实现 chatkit.store.Store 以使用你首选的数据库持久化线程、消息和文件。默认示例使用 SQLite 进行本地开发。
5. 提供文件存储契约
如果你支持上传,请提供 FileStore 实现。ChatKit 支持直接上传(客户端将文件 POST 到你的端点)或两阶段上传(客户端请求签名 URL,然后上传到云存储)。
6. 从服务器触发客户端工具
客户端工具必须同时在客户端选项和智能体上注册。使用 ctx.context.client_tool_call 从 Agents SDK 工具排队调用。
python
@function_tool(description_override="Add an item to the user's todo list.")
async def add_to_todo_list(ctx: RunContextWrapper[AgentContext], item: str) -> None:
ctx.context.client_tool_call = ClientToolCall(
name="add_to_todo_list",
arguments={"item": item},
)
assistant_agent = Agent[AgentContext](
model="gpt-4.1",
name="Assistant",
instructions="You are a helpful assistant",
tools=[add_to_todo_list],
tool_use_behavior=StopAtTools(stop_at_tool_names=[add_to_todo_list.name]),
)添加内联交互式小部件
小部件让智能体在聊天界面内呈现丰富的 UI。将它们用于卡片、表单、文本块、列表和其他布局。
python
async def respond(
self,
thread: ThreadMetadata,
input: UserMessageItem | ClientToolCallOutputItem,
context: Any,
) -> AsyncIterator[Event]:
widget = Card(
children=[Text(
id="description",
value="Generated summary",
)]
)
async for event in stream_widget(
thread,
widget,
generate_id=lambda item_type: self.store.generate_item_id(item_type, thread, context),
):
yield event使用操作
操作让 ChatKit UI 在不发送用户消息的情况下触发工作。将 ActionConfig 附加到任何支持它的小部件节点——按钮、选择和其他控件可以流式传输新线程项目或就地更新小部件。
资源
事件参考
ChatKit 从 Web 组件发出 CustomEvent 实例。有效负载形状为:
typescript
type Events = {
"chatkit.error": CustomEvent<{ error: Error }>;
"chatkit.response.start": CustomEvent<void>;
"chatkit.response.end": CustomEvent<void>;
"chatkit.thread.change": CustomEvent<{ threadId: string | null }>;
"chatkit.log": CustomEvent<{ name: string; data?: Record<string, unknown> }>;
};选项参考
| 选项 | 类型 | 描述 | 默认值 |
|---|---|---|---|
| apiURL | string | 实现 ChatKit 服务器协议的端点。 | 必需 |
| fetch | typeof fetch | 覆盖 fetch 调用(用于自定义标头或身份验证)。 | window.fetch |
| theme | "light" | "dark" | UI 主题。 | "light" |
| initialThread | string | null | 挂载时打开的线程;null 显示新线程视图。 | null |
| clientTools | Record<string, Function> | 暴露给模型的客户端执行工具。 | - |
| header | object | boolean | 标题配置或 false 以隐藏标题。 | true |
| newThreadView | object | 自定义问候文本和启动提示词。 | - |
| messages | object | 配置消息功能(反馈、注释等)。 | - |
| composer | object | 控制附件、实体标签和占位符文本。 | - |
| entities | object | 实体查找、点击处理和预览的回调。 | - |