Skip to content

运行 agents

你可以通过 Runner 类来运行 agents。有三种方式可供选择：

  1. Runner.run()，异步运行并返回 RunResult。
  2. Runner.run_sync()，同步方法，底层其实就是调用了 .run()。
  3. Runner.run_streamed()，异步运行并返回 RunResultStreaming。它以流式模式调用 LLM，并将这些事件实时传输给你。
from agents import Agent, Runner

async def main():
    agent = Agent(name="Assistant", instructions="你是一个乐于助人的助手")

    result = await Runner.run(agent, "写一首关于编程中递归的俳句。")
    print(result.final_output)
    # 代码中的代码，
    # 函数自我调用，
    # 无限循环舞。

更多信息请查看结果指南。

Agent 循环

当你使用 Runner 中的 run 方法时，你需要传入一个起始 agent 和输入。输入可以是字符串（被视为用户消息），或者是输入项列表，即 OpenAI Responses API 中的项目。

然后 runner 会运行一个循环：

  1. 我们用当前输入调用当前 agent 的 LLM。
  2. LLM 产生输出。
    1. 如果 LLM 返回 final_output，循环结束并返回结果。
    2. 如果 LLM 执行 handoff，我们更新当前 agent 和输入，然后重新运行循环。
    3. 如果 LLM 产生工具调用，我们运行这些工具调用，附加结果，然后重新运行循环。
  3. 如果超过传入的 max_turns，我们会抛出 MaxTurnsExceeded 异常。

Note

判断 LLM 输出是否被视为"最终输出"的规则是：它产生了具有所需类型的文本输出，并且没有工具调用。

流式处理

流式处理让你能够在 LLM 运行时接收流式事件。一旦流结束，RunResultStreaming 将包含关于运行的完整信息，包括所有新产生的输出。你可以调用 .stream_events() 获取流式事件。更多信息请查看流式处理指南。

运行配置

run_config 参数让你可以为 agent 运行配置一些全局设置：

  • model：允许设置全局 LLM 模型，不管每个 Agent 有什么 model。
  • model_provider：用于查找模型名称的模型提供者，默认为 OpenAI。
  • model_settings：覆盖 agent 特定的设置。例如，你可以设置全局 temperature 或 top_p。
  • input_guardrails, output_guardrails：要包含在所有运行中的输入或输出防护机制列表。
  • handoff_input_filter：如果 handoff 还没有，则应用于所有 handoff 的全局输入过滤器。输入过滤器允许你编辑发送给新 agent 的输入。更多详情请参阅 Handoff.input_filter 中的文档。
  • tracing_disabled：允许你为整个运行禁用追踪。
  • trace_include_sensitive_data：配置追踪是否包含潜在的敏感数据，如 LLM 和工具调用的输入/输出。
  • workflow_name, trace_id, group_id：设置运行的追踪工作流名称、追踪 ID 和追踪组 ID。我们建议至少设置 workflow_name。会话 ID 是一个可选字段，让你可以链接多个运行的追踪。
  • trace_metadata：要包含在所有追踪中的元数据。

对话/聊天线程

调用任何 run 方法可能导致一个或多个 agents 运行（因此有一个或多个 LLM 调用），但它代表聊天对话中的单个逻辑回合。例如：

  1. 用户回合：用户输入文本
  2. Runner 运行：第一个 agent 调用 LLM，运行工具，执行 handoff 到第二个 agent，第二个 agent 运行更多工具，然后产生输出。

在 agent 运行结束时，你可以选择向用户展示什么。例如，你可能向用户展示 agents 生成的每个新项目，或者只展示最终输出。无论哪种方式，用户可能会问一个后续问题，这时你可以再次调用 run 方法。

你可以使用基础 RunResultBase.to_input_list() 方法获取下一回合的输入。

async def main():
    agent = Agent(name="Assistant", instructions="回复要非常简洁。")

    with trace(workflow_name="对话", group_id=thread_id):
        # 第一回合
        result = await Runner.run(agent, "金门大桥在哪个城市？")
        print(result.final_output)
        # 旧金山

        # 第二回合
        new_input = output.to_input_list() + [{"role": "user", "content": "它在哪个州？"}]
        result = await Runner.run(agent, new_input)
        print(result.final_output)
        # 加利福尼亚

异常

SDK 在某些情况下会抛出异常。完整列表在 agents.exceptions。概述如下：