에이전트 실행하기
에이전트 실행하기
에이전트를 만들었다면 이제 실제로 돌려야겠죠. OpenAI Agents SDK에선 Runner 객체가 에이전트 실행을 책임져요. Runner.run()은 주어진 에이전트와 입력을 받아 모델 호출 → 도구 실행 → (필요하면) 가드레일·핸드오프까지 한 번의 실행 루프로 이어가요. 실행이 끝나면 결과 객체(RunResult)가 최종 출력, 도구 호출, 새로 생긴 항목들을 담아 돌아와요.
동기·비동기·배치 실행
Runner는 상황에 맞는 실행 메서드를 제공해요.
Runner.run_sync(): 동기 실행. 간단한 스크립트나 테스트에 잘 맞아요.Runner.run()/Runner.run_async(): async 함수 안에서 쓰는 비동기 실행이에요.Runner.run_batched()/Runner.run_batched_async(): 여러 입력을 한 번에 묶어 처리할 때 써요.
from agents import Agent, Runner
agent = Agent(name="Helper", instructions="Be concise.")
# 동기
result = Runner.run_sync(agent, "What is 2+2?")
print(result.final_output)
# 비동기 (async 환경)
async def go():
result = await Runner.run(agent, "What is 2+2?")
return result.final_output
실행 결과에서 .final_output은 에이전트의 최종 답변이고, .to_input_list()처럼 뒤에 이어질 입력으로 재사용할 수 있는 형태도 제공해요. 에이전트를 다시 실행할 때 이전 대화 이력(input_list)을 그대로 넘겨 여러 턴의 대화를 이어갈 수 있어요.
스트리밍
LLM이 실행되는 동안 중간 이벤트(도구 호출, 토큰 생성 등)를 실시간으로 받고 싶다면 Runner.run_streamed()를 써요. 이 경우 반환되는 RunResultStreaming을 통해 .stream_events()로 이벤트를 순회(sync)하거나 astream_events()로 비동기 순회할 수 있어요. 스트림이 끝나면 결과 객체에 실행 전체의 정보가 담겨 있어요.
from agents import Agent, Runner
agent = Agent(name="Assistant", instructions="Answer briefly.")
result = Runner.run_streamed(agent, "Tell me a fun fact")
async for event in result.stream_events():
# 이벤트 타입에 따라 처리를 나눌 수 있어요
pass
print(result.final_output)
각 이벤트 타입(RunItemStreamEvent 등)은 agents.event에서 확인할 수 있어요. 자세한 이벤트별 처리법은 streaming 가이드를 참고하면 돼요.
실행 중단과 예외
Runner.run() 및 스트리밍 버전은 await result.cancel() 같은 방식으로 중단을 지원해요. SDK가 예외를 발생시키는 상황은 agents.exceptions에 정리되어 있어서, 특정 에러를 잡아서 UX를 개선하고 싶을 때 여기서 유형별 처리를 확인하면 좋아요.
실행 설정 (RunConfig)
실행별 동작을 바꿔야 할 때는 Runner.run(agent, input, run_config=...) 형태로 RunConfig를 넘겨요. 가드레일·핸드오프·모델 입력 구성, 핸드오프 히스토리 중첩(nest_handoff_history) 같은 옵션이 여기에 묶여 있어요. 출력 가드레일이 차단했을 때 사용할 자리를 정하는 output_guardrail_blocked_message 같은 항목도 이 설정에서 다뤄요.