콘텐츠로 이동

결과

Runner.run 메서드를 호출하면 두 가지 결과 타입 중 하나를 받습니다:

두 타입 모두 RunResultBase를 상속하며, final_output, new_items, last_agent, raw_responses, to_state() 같은 공통 결과 표면을 제공합니다

RunResultStreaming은 stream_events(), current_agent, is_complete, cancel(...) 같은 스트리밍 전용 제어 기능을 추가로 제공합니다

올바른 결과 표면 선택

대부분의 애플리케이션은 몇 가지 결과 속성이나 헬퍼만 필요합니다:

다음이 필요할 때... 사용
사용자에게 보여줄 최종 응답 final_output
전체 로컬 기록이 포함된, 재생 가능한 다음 턴 입력 목록 to_input_list()
에이전트, 도구, 핸드오프, 승인 메타데이터가 포함된 풍부한 실행 아이템 new_items
일반적으로 다음 사용자 턴을 처리해야 하는 에이전트 last_agent
previous_response_id를 사용하는 OpenAI Responses API 체이닝 last_response_id
보류 중인 승인 및 재개 가능한 스냅샷 interruptions 및 to_state()
현재 중첩된 Agent.as_tool() 호출에 대한 메타데이터 agent_tool_invocation
원시 모델 호출 또는 가드레일 진단 raw_responses 및 가드레일 결과 배열

최종 출력

final_output 속성은 마지막으로 실행된 에이전트의 최종 출력을 포함합니다. 이는 다음 중 하나입니다:

  • 마지막 에이전트에 output_type이 정의되지 않은 경우 str
  • 마지막 에이전트에 출력 타입이 정의된 경우 last_agent.output_type 타입의 객체
  • 최종 출력이 생성되기 전에 실행이 중지된 경우 None(예: 승인 인터럽션(중단 처리)에서 일시 중지된 경우)

Note

final_output의 타입은 Any입니다. 핸드오프가 실행을 완료하는 에이전트를 변경할 수 있으므로, SDK는 가능한 출력 타입의 전체 집합을 정적으로 알 수 없습니다

스트리밍 모드에서는 스트림 처리가 끝날 때까지 final_output이 None으로 유지됩니다. 이벤트별 흐름은 Streaming을 참고하세요

입력, 다음 턴 기록, 새 아이템

이 표면들은 서로 다른 질문에 답합니다:

속성 또는 헬퍼 포함 내용 적합한 용도
input 이 실행 세그먼트의 기본 입력. 핸드오프 입력 필터가 기록을 다시 쓴 경우, 실행이 이어진 필터링된 입력을 반영합니다 이 실행이 실제로 어떤 입력을 사용했는지 감사
to_input_list() 실행의 입력 아이템 뷰. 기본 mode="preserve_all"은 new_items에서 변환된 전체 기록을 유지하며, mode="normalized"는 핸드오프 필터링이 모델 기록을 다시 쓸 때 정규화된 연속 입력을 우선합니다 수동 채팅 루프, 클라이언트 관리 대화 상태, 일반 아이템 기록 점검
new_items 에이전트, 도구, 핸드오프, 승인 메타데이터가 포함된 풍부한 RunItem 래퍼 로그, UI, 감사, 디버깅
raw_responses 실행의 각 모델 호출에서 나온 원시 ModelResponse 객체 제공자 수준 진단 또는 원시 응답 점검

실제로는 다음과 같습니다:

  • 실행의 일반 입력 아이템 뷰가 필요하면 to_input_list()를 사용하세요
  • 핸드오프 필터링 또는 중첩 핸드오프 기록 재작성 이후 다음 Runner.run(..., input=...) 호출에 사용할 정규화된 로컬 입력이 필요하면 to_input_list(mode="normalized")를 사용하세요
  • SDK가 기록을 대신 로드/저장하도록 하려면 session=...을 사용하세요
  • conversation_id 또는 previous_response_id로 OpenAI 서버 관리 상태를 사용하는 경우, 보통 to_input_list()를 다시 보내기보다 새 사용자 입력만 전달하고 저장된 ID를 재사용하세요
  • 로그, UI, 감사용으로 전체 변환 기록이 필요하면 기본 to_input_list() 모드 또는 new_items를 사용하세요

JavaScript SDK와 달리 Python은 모델 형태 델타 전용의 별도 output 속성을 제공하지 않습니다. SDK 메타데이터가 필요하면 new_items를 사용하고, 원시 모델 페이로드가 필요하면 raw_responses를 확인하세요

컴퓨터 도구 재생은 원시 Responses 페이로드 형태를 따릅니다. 프리뷰 모델의 computer_call 아이템은 단일 action을 유지하고, gpt-5.4 컴퓨터 호출은 일괄 actions[]를 유지할 수 있습니다. to_input_list()와 RunState는 모델이 생성한 형태를 그대로 유지하므로, 수동 재생, 일시 중지/재개 흐름, 저장된 기록이 프리뷰와 GA 컴퓨터 도구 호출 모두에서 계속 동작합니다. 로컬 실행 결과는 여전히 new_items의 computer_call_output 아이템으로 나타납니다

새 아이템

new_items는 실행 중 발생한 일을 가장 풍부하게 보여줍니다. 일반적인 아이템 타입은 다음과 같습니다:

에이전트 연관성, 도구 출력, 핸드오프 경계, 승인 경계가 필요할 때는 to_input_list()보다 new_items를 선택하세요

호스티드 툴 검색을 사용할 때는 모델이 생성한 검색 요청을 보려면 ToolSearchCallItem.raw_item을, 해당 턴에서 어떤 네임스페이스, 함수, 또는 호스티드 MCP 서버가 로드되었는지 보려면 ToolSearchOutputItem.raw_item을 확인하세요

대화 계속 또는 재개

다음 턴 에이전트

last_agent에는 마지막으로 실행된 에이전트가 들어 있습니다. 핸드오프 이후 다음 사용자 턴에서 재사용할 최적의 에이전트인 경우가 많습니다

스트리밍 모드에서는 실행이 진행됨에 따라 RunResultStreaming.current_agent가 업데이트되므로, 스트림이 끝나기 전에도 핸드오프를 관찰할 수 있습니다

인터럽션(중단 처리) 및 실행 상태

도구에 승인이 필요하면 보류 중인 승인 항목이 RunResult.interruptions 또는 RunResultStreaming.interruptions에 노출됩니다. 여기에는 직접 도구에서 발생한 승인, 핸드오프 이후 도달한 도구에서 발생한 승인, 중첩된 Agent.as_tool() 실행에서 발생한 승인이 포함될 수 있습니다

재개 가능한 RunState를 캡처하려면 to_state()를 호출하고, 보류 중인 아이템을 승인 또는 거부한 다음, Runner.run(...) 또는 Runner.run_streamed(...)로 재개하세요

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="Use tools when needed.")
result = await Runner.run(agent, "Delete temp files that are no longer needed.")

if result.interruptions:
    state = result.to_state()
    for interruption in result.interruptions:
        state.approve(interruption)
    result = await Runner.run(agent, state)

스트리밍 실행의 경우 먼저 stream_events() 소비를 완료한 다음 result.interruptions를 확인하고 result.to_state()에서 재개하세요. 전체 승인 흐름은 Human-in-the-loop를 참고하세요

서버 관리 연속 실행

last_response_id는 실행의 최신 모델 응답 ID입니다. OpenAI Responses API 체인을 이어가려면 다음 턴에서 이를 previous_response_id로 다시 전달하세요

이미 to_input_list(), session, 또는 conversation_id로 대화를 이어가고 있다면 보통 last_response_id는 필요하지 않습니다. 다단계 실행의 모든 모델 응답이 필요하면 대신 raw_responses를 확인하세요

Agent-as-tool 메타데이터

결과가 중첩된 Agent.as_tool() 실행에서 온 경우, agent_tool_invocation은 바깥 도구 호출에 대한 불변 메타데이터를 제공합니다:

  • tool_name
  • tool_call_id
  • tool_arguments

일반적인 최상위 실행에서는 agent_tool_invocation이 None입니다

이는 특히 custom_output_extractor 내부에서 유용합니다. 중첩 결과를 후처리하는 동안 바깥 도구 이름, 호출 ID, 또는 원시 인자가 필요할 수 있기 때문입니다. 주변 Agent.as_tool() 패턴은 Tools를 참고하세요

해당 중첩 실행의 파싱된 구조화 입력도 필요하다면 context_wrapper.tool_input을 읽으세요. 이는 중첩 도구 입력에 대해 RunState가 일반적으로 직렬화하는 필드이며, agent_tool_invocation은 현재 중첩 호출을 위한 실시간 결과 접근자입니다

스트리밍 수명 주기 및 진단

RunResultStreaming은 위와 동일한 결과 표면을 상속하지만, 스트리밍 전용 제어 기능을 추가합니다:

비동기 이터레이터가 끝날 때까지 stream_events() 소비를 계속하세요. 스트리밍 실행은 해당 이터레이터가 종료되어야 완료되며, 마지막으로 보이는 토큰이 도착한 뒤에도 final_output, interruptions, raw_responses, 세션 영속화 부작용 같은 요약 속성은 아직 정리 중일 수 있습니다

cancel()을 호출한 경우에도 취소 및 정리가 올바르게 완료되도록 stream_events() 소비를 계속하세요

Python은 별도의 스트리밍 completed promise나 error 속성을 제공하지 않습니다. 최종 스트리밍 실패는 stream_events()에서 예외를 발생시키는 방식으로 표면화되며, is_complete는 실행이 최종 상태에 도달했는지를 반영합니다

원시 응답

raw_responses에는 실행 중 수집된 원시 모델 응답이 포함됩니다. 다단계 실행에서는 예를 들어 핸드오프 또는 반복적인 모델/도구/모델 사이클 전반에 걸쳐 둘 이상의 응답이 생성될 수 있습니다

last_response_id는 raw_responses의 마지막 항목 ID일 뿐입니다

가드레일 결과

에이전트 수준 가드레일은 input_guardrail_results와 output_guardrail_results로 노출됩니다

도구 가드레일은 tool_input_guardrail_results와 tool_output_guardrail_results로 별도로 노출됩니다

이 배열들은 실행 전반에 걸쳐 누적되므로, 결정 사항 로깅, 추가 가드레일 메타데이터 저장, 또는 실행이 차단된 이유 디버깅에 유용합니다

컨텍스트 및 사용량

context_wrapper는 승인, 사용량, 중첩 tool_input 같은 SDK 관리 런타임 메타데이터와 함께 앱 컨텍스트를 제공합니다

사용량은 context_wrapper.usage에서 추적됩니다. 스트리밍 실행에서는 스트림의 최종 청크가 처리될 때까지 사용량 합계가 지연될 수 있습니다. 전체 래퍼 형태와 영속성 주의사항은 Context management를 참고하세요