英文文档原文详见 OpenAI Agents SDKhttps://openai.github.io/openai-agents-python/
本文是OpenAI-agents-sdk-python使用翻译软件翻译后的中文文档/教程。分多个帖子发布,帖子的目录如下:
(1) OpenAI 代理 SDK, 介绍及快速入门
(2)OpenAI agents sdk, agents,运行agents,结果,流,工具,交接
(3) OpenAi agents sdk, 跟踪,上下文管理,护栏
(4) Openai agents sdk, 编排多个代理,模型,配置SDK
(5)(6)..等等,后面的都放到openai agents sdk的这个专栏https://blog.csdn.net/wtsolutions/category_12916751.html里面了,大家可以到专栏里面看到所有的目录,欢迎订阅这个专栏。
目录
代理模块
set_default_openai_key
set_default_openai_client
set_default_openai_api
set_tracing_export_api_key
set_tracing_disabled
set_trace_processors
enable_verbose_stdout_logging
Agents
代理 数据类
name 实例属性
instructions 类-属性 instance-attribute
handoff_description 类属性 instance-attribute
handoffs 类-attribute 实例-属性
model 类-属性 instance-attribute
model_settings 类属性实例属性
tools 类-属性 instance-attribute
input_guardrails 类属性实例属性
output_guardrails 类属性 instance-attribute
output_type 类属性 instance-attribute
hooks 类属性 instance-attribute
克隆
as_tool
get_system_prompt async
Runner
跑步者
Run async 类方法
run_sync 类方法
run_streamed classmethod
RunConfig dataclass
model class-attribute instance-attribute
model_provider class-attribute instance-attribute
model_settings class-attribute instance-attribute
handoff_input_filter class-attribute instance-attribute
input_guardrails class-attribute instance-attribute
output_guardrails class-attribute instance-attribute
tracing_disabled class-attribute instance-attribute
trace_include_sensitive_data 类属性 instance-attribute
workflow_name 类属性 instance-attribute
trace_id 类属性 instance-attribute
group_id 类属性实例属性
trace_metadata 类属性实例属性
代理模块
set_default_openai_key
set_default_openai_key(key: str, use_for_tracing: bool = True
) -> None
设置用于 LLM 请求的默认 OpenAI API 密钥(以及可选的 tracing())。这是 仅当尚未设置 OPENAI_API_KEY 环境变量时才需要。
如果提供,将使用此键而不是 OPENAI_API_KEY 环境变量。
参数:
名字 | 类型 | 描述 | 违约 |
---|---|---|---|
key | str | 要使用的 OpenAI 密钥。 | 必填 |
use_for_tracing | bool | 是否也使用此 key 向 OpenAI 发送跟踪。默认为 True 如果为 False,则需要设置 OPENAI_API_KEY 环境变量或调用 set_tracing_export_api_key() 替换为要用于跟踪的 API 密钥。 | True |
src/agents/__init__.py
set_default_openai_client
set_default_openai_client(client: AsyncOpenAI, use_for_tracing: bool = True
) -> None
set_default_openai_api
set_default_openai_api(api: Literal["chat_completions", "responses"],
) -> None
set_tracing_export_api_key
set_tracing_export_api_key(api_key: str) -> None
set_tracing_disabled
set_tracing_disabled(disabled: bool) -> None
set_trace_processors
set_trace_processors(processors: list[TracingProcessor],
) -> None
Agents
代理 数据类
基地:Generic[TContext]
代理是一种 AI 模型,配置了说明、工具、护栏、交接等。
我们强烈建议传递 ,这是代理的 “system prompt”。在 此外,您还可以将 ,这是代理的人类可读描述,用于 在 Tools/Handoffs 中使用代理时。instructions
description
代理在上下文类型上是通用的。上下文是您创建的 (可变) 对象。是的 传递给工具函数、交接、护栏等。
源码src/agents/agent.py
name 实例属性
name: str
代理的名称。
instructions 类-属性
instance-attribute
instructions: (str| Callable[[RunContextWrapper[TContext], Agent[TContext]],MaybeAwaitable[str],]| None
) = None
代理的说明。当这个 agent 是 时,会作为 “system prompt” 调用。描述代理应执行的作以及它的响应方式。
可以是字符串,也可以是为代理动态生成指令的函数。如果 您提供了一个函数,它将使用 Context 和 Agent 实例调用。它必须 返回一个字符串。
handoff_description 类属性
instance-attribute
handoff_description: str | None = None
代理的描述。当代理用作切换时,会使用此 URL,以便 LLM 知道它的作用以及何时调用它。
handoffs 类-attribute
实例-属性
handoffs: list[Agent[Any] | Handoff[TContext]] = field(default_factory=list
)
Handoff 是代理可以委派给的子代理。您可以提供 handoffs 列表, 代理可以选择委托给他们(如果相关)。允许分离关注点和 模块性。
model 类-属性
instance-attribute
model: str | Model | None = None
调用 LLM 时要使用的模型实现。
默认情况下,如果未设置,代理将使用 中配置的默认模型。model_settings.DEFAULT_MODEL
model_settings 类属性
实例属性
model_settings: ModelSettings = field(default_factory=ModelSettings
)
配置特定于模型的优化参数(例如 temperature、top_p)。
tools 类-属性
instance-attribute
tools: list[Tool] = field(default_factory=list)
代理可以使用的工具列表。
input_guardrails 类属性
实例属性
input_guardrails: list[InputGuardrail[TContext]] = field(default_factory=list
)
在生成 响应。仅当代理是链中的第一个代理时,才运行。
output_guardrails 类属性
instance-attribute
output_guardrails: list[OutputGuardrail[TContext]] = field(default_factory=list
)
生成响应后,对代理的最终输出运行的检查列表。 仅当代理生成最终输出时运行。
output_type 类属性
instance-attribute
output_type: type[Any] | None = None
输出对象的类型。如果未提供,则输出将为 。str
hooks 类属性
instance-attribute
hooks: AgentHooks[TContext] | None = None
一个类,用于接收此代理的各种生命周期事件的回调。
克隆
clone(**kwargs: Any) -> Agent[TContext]
as_tool
as_tool(tool_name: str | None,tool_description: str | None,custom_output_extractor: Callable[[RunResult], Awaitable[str]]| None = None,
) -> Tool
将此代理转换为可由其他代理调用的工具。
这与 handoffs 在两个方面不同: 1. 在交接中,新座席会收到对话历史记录。在此工具中,新代理 接收生成的 Input。 2. 在交接中,新座席接管对话。在此工具中,新代理是 作为工具调用,并且对话由原始代理继续。
参数:
名字 | 类型 | 描述 | 违约 |
---|---|---|---|
tool_name | str | None | 工具的名称。如果未提供,将使用代理的名称。 | 必填 |
tool_description | str | None | 工具的描述,应说明它的作用以及 何时使用它。 | 必填 |
custom_output_extractor | Callable[[RunResult], Awaitable[str]] | None | 从代理中提取输出的函数。如果不是 ,则将使用来自代理的最后一条消息。 | None |
src/agents/agent.py
Runner
跑步者
src/agents/run.py
Run async
类方法
run(starting_agent: Agent[TContext],input: str | list[TResponseInputItem],*,context: TContext | None = None,max_turns: int = DEFAULT_MAX_TURNS,hooks: RunHooks[TContext] | None = None,run_config: RunConfig | None = None,
) -> RunResult
从给定代理开始运行工作流程。代理将循环运行,直到最终 output 生成。循环运行如下: 1. 使用给定的输入调用代理。 2. 如果有最终输出(即代理生成 type 为 的东西),则循环终止。 3. 如果有切换,我们将使用新代理再次运行循环。 4. 否则,我们将运行工具调用(如果有),然后重新运行循环。agent.output_type
在两种情况下,代理可能会引发异常: 1. 如果超出max_turns,则会引发 MaxTurnsExceeded 异常。 2. 如果触发了护栏绊线,则会引发 GuardrailTripwireTriggered 异常。
请注意,仅运行第一个代理的输入护栏。
参数:
名字 | 类型 | 描述 | 违约 |
---|---|---|---|
starting_agent | Agent[TContext] | 要运行的启动代理。 | 必填 |
input | str | list[TResponseInputItem] | 代理的初始输入。您可以为用户消息传递单个字符串 或输入项列表。 | 必填 |
context | TContext | None | 用于运行代理的上下文。 | None |
max_turns | int | 运行代理的最大轮次。一个转弯定义为 1 AI 调用(包括可能发生的任何工具调用)。 | DEFAULT_MAX_TURNS |
hooks | RunHooks[TContext] | None | 一个对象,用于接收各种生命周期事件的回调。 | None |
run_config | RunConfig | None | 整个代理运行的全局设置。 | None |
返回:
类型 | 描述 |
---|---|
RunResult | 包含所有输入、护栏结果和最后一个 |
RunResult | 代理。代理可能会执行切换,因此我们不知道输出的具体类型。 |
src/agents/run.py
run_sync 类方法
run_sync(starting_agent: Agent[TContext],input: str | list[TResponseInputItem],*,context: TContext | None = None,max_turns: int = DEFAULT_MAX_TURNS,hooks: RunHooks[TContext] | None = None,run_config: RunConfig | None = None,
) -> RunResult
从给定代理开始同步运行工作流程。请注意,这只是包装了方法,因此如果已经存在一个事件循环(例如,在 async 中 函数,或者在 Jupyter 笔记本或异步上下文(如 FastAPI)中)。对于这些情况,请使用 方法。run
run
代理将在循环中运行,直到生成最终输出。循环运行如下: 1. 使用给定的输入调用代理。 2. 如果有最终输出(即代理生成 type 为 的东西),则循环终止。 3. 如果有切换,我们将使用新代理再次运行循环。 4. 否则,我们将运行工具调用(如果有),然后重新运行循环。agent.output_type
在两种情况下,代理可能会引发异常: 1. 如果超出max_turns,则会引发 MaxTurnsExceeded 异常。 2. 如果触发了护栏绊线,则会引发 GuardrailTripwireTriggered 异常。
请注意,仅运行第一个代理的输入护栏。
参数:
名字 | 类型 | 描述 | 违约 |
---|---|---|---|
starting_agent | Agent[TContext] | 要运行的启动代理。 | 必填 |
input | str | list[TResponseInputItem] | 代理的初始输入。您可以为用户消息传递单个字符串 或输入项列表。 | 必填 |
context | TContext | None | 用于运行代理的上下文。 | None |
max_turns | int | 运行代理的最大轮次。一个转弯定义为 1 AI 调用(包括可能发生的任何工具调用)。 | DEFAULT_MAX_TURNS |
hooks | RunHooks[TContext] | None | 一个对象,用于接收各种生命周期事件的回调。 | None |
run_config | RunConfig | None | 整个代理运行的全局设置。 | None |
返回:
类型 | 描述 |
---|---|
RunResult | 包含所有输入、护栏结果和最后一个 |
RunResult | 代理。代理可能会执行切换,因此我们不知道输出的具体类型。 |
src/agents/run.py
run_streamed 类方法
run_streamed(starting_agent: Agent[TContext],input: str | list[TResponseInputItem],context: TContext | None = None,max_turns: int = DEFAULT_MAX_TURNS,hooks: RunHooks[TContext] | None = None,run_config: RunConfig | None = None,
) -> RunResultStreaming
在流式处理模式下从给定代理运行工作流。返回的 result 对象 包含可用于在生成语义事件时对其进行流式处理的方法。
代理将在循环中运行,直到生成最终输出。循环运行如下: 1. 使用给定的输入调用代理。 2. 如果有最终输出(即代理生成 type 为 的东西),则循环终止。 3. 如果有切换,我们将使用新代理再次运行循环。 4. 否则,我们将运行工具调用(如果有),然后重新运行循环。agent.output_type
在两种情况下,代理可能会引发异常: 1. 如果超出max_turns,则会引发 MaxTurnsExceeded 异常。 2. 如果触发了护栏绊线,则会引发 GuardrailTripwireTriggered 异常。
请注意,仅运行第一个代理的输入护栏。
参数:
名字 | 类型 | 描述 | 违约 |
---|---|---|---|
starting_agent | Agent[TContext] | 要运行的启动代理。 | 必填 |
input | str | list[TResponseInputItem] | 代理的初始输入。您可以为用户消息传递单个字符串 或输入项列表。 | 必填 |
context | TContext | None | 用于运行代理的上下文。 | None |
max_turns | int | 运行代理的最大轮次。一个转弯定义为 1 AI 调用(包括可能发生的任何工具调用)。 | DEFAULT_MAX_TURNS |
hooks | RunHooks[TContext] | None | 一个对象,用于接收各种生命周期事件的回调。 | None |
run_config | RunConfig | None | 整个代理运行的全局设置。 | None |
返回:
类型 | 描述 |
---|---|
RunResultStreaming | 一个 result 对象,其中包含有关运行的数据,以及用于流式传输事件的方法。 |
src/agents/run.py
RunConfig 数据类
配置整个代理程序运行的设置。
源码src/agents/run.py
model 类-属性
instance-attribute
model: str | Model | None = None
用于整个代理运行的模型。如果设置,将覆盖在每个 代理。下面传入的 model_provider 必须能够解析此模型名称。
model_provider 类属性
实例属性
model_provider: ModelProvider = field(default_factory=OpenAIProvider
)
查找字符串模型名称时使用的模型提供程序。默认为 OpenAI。
model_settings 类属性
实例属性
model_settings: ModelSettings | None = None
配置全局模型设置。任何非 null 值都将覆盖特定于代理的模型 设置。
handoff_input_filter 类属性
实例属性
handoff_input_filter: HandoffInputFilter | None = None
应用于所有 handoff 的全局输入过滤器。如果已设置,则 将优先。输入过滤器允许您编辑发送到新 代理。有关更多详细信息,请参阅 中的文档。Handoff.input_filter
Handoff.input_filter
input_guardrails 类属性
实例属性
input_guardrails: list[InputGuardrail[Any]] | None = None
要在初始运行输入上运行的输入护栏列表。
output_guardrails 类属性
instance-attribute
output_guardrails: list[OutputGuardrail[Any]] | None = None
要在运行的最终输出上运行的输出护栏列表。
tracing_disabled 类属性
instance-attribute
tracing_disabled: bool = False
是否为代理运行禁用跟踪。如果禁用,我们将不会跟踪代理运行。
trace_include_sensitive_data 类属性
instance-attribute
trace_include_sensitive_data: bool = True
我们是否包含可能敏感的数据(例如:工具调用的输入/输出或 LLM 代)的 Trace 中。如果为 False,我们仍将为这些事件创建 span,但 敏感数据将不包括在内。
workflow_name 类属性
instance-attribute
workflow_name: str = 'Agent workflow'
运行的名称,用于跟踪。应该是运行的逻辑名称,例如 “代码生成工作流”或“客户支持代理”。
trace_id 类属性
instance-attribute
trace_id: str | None = None
用于跟踪的自定义跟踪 ID。如果未提供,我们将生成新的跟踪 ID。
group_id 类属性
实例属性
group_id: str | None = None
用于跟踪的分组标识符,用于链接同一对话中的多个跟踪 或过程。例如,您可以使用聊天会话 ID。
trace_metadata 类属性
实例属性
trace_metadata: dict[str, Any] | None = None
要包含在跟踪中的其他元数据的可选字典。