跳转至

运行 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="You are a helpful assistant")

    result = await Runner.run(agent, "Write a haiku about recursion in programming.")
    print(result.final_output)
    # 代码中的代码，
    # 函数自我调用，
    # 无限循环之舞。

更多内容请参阅结果指南。

agent 循环流程

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

运行器随后执行以下循环：

  1. 使用当前输入调用当前 agent 的 LLM。
  2. LLM 生成输出：
    1. 如果 LLM 返回 final_output，循环结束并返回结果。
    2. 如果 LLM 执行交接操作，则更新当前 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: 应用于所有交接的全局输入过滤器（如果交接本身未定义）。输入过滤器允许您编辑发送给新 agent 的输入内容。详情请参阅 Handoff.input_filter 文档。
  • tracing_disabled: 允许禁用整个运行的追踪功能。
  • trace_include_sensitive_data: 配置追踪记录是否包含潜在敏感数据，例如 LLM 和工具调用的输入/输出。
  • workflow_name, trace_id, group_id: 设置运行的追踪工作流名称、追踪 ID 和追踪组 ID。我们建议至少设置 workflow_name。组 ID 是可选字段，可用于关联多个运行的追踪记录。
  • trace_metadata: 包含在所有追踪记录中的元数据。

对话/聊天线程

调用任何运行方法都可能导致一个或多个 agents 执行（从而产生一次或多次 LLM 调用），但它代表聊天对话中的单个逻辑轮次。例如：

  1. 用户轮次：用户输入文本
  2. 运行器执行：第一个 agent 调用 LLM、运行工具、交接给第二个 agent，第二个 agent 运行更多工具，然后产生输出。

在 agent 运行结束时，您可以选择向用户展示的内容。例如，您可以向用户展示 agents 生成的每个新条目，或者仅展示最终输出。无论哪种方式，用户都可能随后提出后续问题，这时您可以再次调用运行方法。

您可以使用基础方法 RunResultBase.to_input_list() 来获取下一轮次的输入。

async def main():
    agent = Agent(name="Assistant", instructions="Reply very concisely.")

    with trace(workflow_name="Conversation", group_id=thread_id):
        # 第一轮次
        result = await Runner.run(agent, "What city is the Golden Gate Bridge in?")
        print(result.final_output)
        # San Francisco

        # 第二轮次
        new_input = result.to_input_list() + [{"role": "user", "content": "What state is it in?"}]
        result = await Runner.run(agent, new_input)
        print(result.final_output)
        # California

异常处理

SDK 在特定情况下会抛出异常。完整列表参见 agents.exceptions，主要包含以下类别：