跳至内容

运行代理

您可以通过Runner类来运行代理。您有3种选择：

  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)
    # Code within the code,
    # Functions calling themselves,
    # Infinite loop's dance.

了解更多信息，请参阅结果指南。

代理循环

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

然后运行器会执行一个循环：

  1. 我们调用当前代理的LLM，并传入当前输入。
  2. The LLM produces its output.
    1. 如果LLM返回一个final_output，循环结束并返回结果。
    2. 如果LLM执行了交接操作，我们会更新当前代理和输入，并重新运行循环。
    3. 如果LLM生成工具调用，我们会执行这些工具调用，追加结果，然后重新运行循环。
  3. 如果我们超过了传入的max_turns值，就会抛出一个MaxTurnsExceeded异常。

注意

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

流式传输

流式传输功能允许您在LLM运行时额外接收流式事件。当流式传输完成后，RunResultStreaming将包含有关运行的完整信息，包括所有新生成的输出。您可以调用.stream_events()来获取流式事件。更多详情请参阅流式传输指南。

运行配置

run_config 参数允许您为代理运行配置一些全局设置：

  • model: 允许设置一个全局的LLM模型供使用，而不受每个Agent的model设置影响。
  • model_provider: 用于查找模型名称的模型提供者，默认为OpenAI。
  • model_settings: 覆盖代理特定的设置。例如，您可以设置全局的 temperature 或 top_p。
  • input_guardrails, output_guardrails: 在所有运行中包含的输入或输出防护栏列表。
  • handoff_input_filter: 一个全局输入过滤器，将应用于所有交接操作（如果交接操作尚未设置过滤器）。输入过滤器允许您编辑发送给新代理的输入内容。更多详情请参阅Handoff.input_filter中的文档。
  • tracing_disabled: 允许您为整个运行禁用追踪。
  • trace_include_sensitive_data: 配置跟踪是否包含潜在敏感数据，例如LLM和工具调用的输入/输出。
  • workflow_name, trace_id, group_id: 为运行设置追踪工作流名称、追踪ID和追踪组ID。我们建议至少设置workflow_name。会话ID是一个可选字段，可让您跨多个运行链接追踪。
  • trace_metadata: 要包含在所有追踪中的元数据。

对话/聊天线程

调用任何一个运行方法都可能导致一个或多个代理运行（因此会进行一次或多次LLM调用），但这代表聊天对话中的单个逻辑轮次。例如：

  1. 用户回合：用户输入文本
  2. Runner运行流程：第一个代理调用LLM，运行工具，将任务移交给第二个代理，第二个代理运行更多工具，然后生成输出。

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

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

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

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

        # Second turn
        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。以下是概述：