에이전트

에이전트는 앱의 핵심 구성 요소입니다. 에이전트는 instructions 와 tools 로 구성된 대규모 언어 모델(LLM)입니다.

기본 구성

에이전트를 설정할 때 가장 일반적으로 구성하는 속성은 다음과 같습니다:

name: 에이전트를 식별하는 필수 문자열
instructions: 개발자 메시지 또는 system prompt 라고도 함
model: 사용할 LLM 및 temperature, top_p 등 모델 튜닝 매개변수를 설정하는 선택적model_settings
tools: 에이전트가 작업을 수행하는 데 사용할 수 있는 도구

fromagentsimportAgent,ModelSettings,function_tool@function_tooldefget_weather(city:str)->str:"""returns weather info for the specified city."""returnf"The weather in{city} is sunny"agent=Agent(name="Haiku agent",instructions="Always respond in haiku form",model="gpt-5-nano",tools=[get_weather],)

컨텍스트

에이전트는context 타입을 제네릭으로 받습니다. 컨텍스트는 의존성 주입 도구입니다. 당신이 생성하여Runner.run() 에 전달하는 객체로, 모든 에이전트, 도구, 핸드오프 등에 전달되며 에이전트 실행을 위한 의존성과 상태의 보관함 역할을 합니다. 컨텍스트로는 어떤 Python 객체든 제공할 수 있습니다.

@dataclassclassUserContext:name:struid:stris_pro_user:boolasyncdeffetch_purchases()->list[Purchase]:return...agent=Agent[UserContext](...,)

출력 유형

기본적으로 에이전트는 일반 텍스트(즉,str) 출력을 생성합니다. 에이전트가 특정 유형의 출력을 생성하도록 하려면output_type 매개변수를 사용할 수 있습니다. 일반적인 선택은Pydantic 객체를 사용하는 것이지만, PydanticTypeAdapter 로 래핑할 수 있는 모든 타입(데이터클래스, 리스트, TypedDict 등)을 지원합니다.

frompydanticimportBaseModelfromagentsimportAgentclassCalendarEvent(BaseModel):name:strdate:strparticipants:list[str]agent=Agent(name="Calendar extractor",instructions="Extract calendar events from text",output_type=CalendarEvent,)

Note

output_type 을 전달하면 일반 텍스트 응답 대신structured outputs 을 사용하도록 모델에 지시합니다.

멀티 에이전트 시스템 설계 패턴

멀티 에이전트 시스템을 설계하는 방법은 다양하지만, 일반적으로 폭넓게 적용 가능한 두 가지 패턴이 있습니다:

매니저(에이전트를 도구로 사용): 중앙 매니저/오케스트레이터가 특화된 하위 에이전트를 도구처럼 호출하며 대화를 계속 제어함
핸드오프: 동등한 에이전트 간에 제어를 특화된 에이전트로 넘겨 그 에이전트가 대화를 이어받는 분산형 방식

자세한 내용은에이전트 구축 실용 가이드 를 참조하세요.

매니저(에이전트를 도구로 사용)

customer_facing_agent 가 모든 사용자 상호작용을 처리하고, 도구로 노출된 특화된 하위 에이전트를 호출합니다. 자세한 내용은도구 문서를 참조하세요.

fromagentsimportAgentbooking_agent=Agent(...)refund_agent=Agent(...)customer_facing_agent=Agent(name="Customer-facing agent",instructions=("Handle all direct user communication. ""Call the relevant tools when specialized expertise is needed."),tools=[booking_agent.as_tool(tool_name="booking_expert",tool_description="Handles booking questions and requests.",),refund_agent.as_tool(tool_name="refund_expert",tool_description="Handles refund questions and requests.",)],)

핸드오프

핸드오프는 에이전트가 위임할 수 있는 하위 에이전트입니다. 핸드오프가 발생하면 위임받은 에이전트가 대화 기록을 전달받아 대화를 이어받습니다. 이 패턴은 단일 작업에 특화된 모듈식 에이전트를 가능하게 합니다. 자세한 내용은핸드오프 문서를 참조하세요.

fromagentsimportAgentbooking_agent=Agent(...)refund_agent=Agent(...)triage_agent=Agent(name="Triage agent",instructions=("Help the user with their questions. ""If they ask about booking, hand off to the booking agent. ""If they ask about refunds, hand off to the refund agent."),handoffs=[booking_agent,refund_agent],)

동적 instructions

대부분의 경우 에이전트를 생성할 때 instructions 를 제공하면 됩니다. 하지만 함수로 동적 instructions 를 제공할 수도 있습니다. 이 함수는 에이전트와 컨텍스트를 입력받아 프롬프트를 반환해야 합니다. 동기 및async 함수 모두 허용됩니다.

defdynamic_instructions(context:RunContextWrapper[UserContext],agent:Agent[UserContext])->str:returnf"The user's name is{context.context.name}. Help them with their questions."agent=Agent[UserContext](name="Triage agent",instructions=dynamic_instructions,)

라이프사이클 이벤트(훅)

때로는 에이전트의 라이프사이클을 관찰하고 싶을 수 있습니다. 예를 들어, 이벤트를 로깅하거나 특정 이벤트 발생 시 데이터를 미리 가져오고 싶을 수 있습니다.hooks 속성으로 에이전트 라이프사이클에 훅을 연결할 수 있습니다.AgentHooks 클래스를 상속하고 관심 있는 메서드를 오버라이드하세요.

가드레일

가드레일을 사용하면 에이전트가 실행되는 동안 사용자 입력에 대한 검사/검증을 병렬로 수행하고, 에이전트 출력이 생성된 후에도 검사할 수 있습니다. 예를 들어, 사용자 입력과 에이전트 출력을 관련성 기준으로 선별할 수 있습니다. 자세한 내용은가드레일 문서를 참조하세요.

에이전트 복제/복사

에이전트의clone() 메서드를 사용하면 에이전트를 복제하고, 원하는 속성을 선택적으로 변경할 수 있습니다.

pirate_agent=Agent(name="Pirate",instructions="Write like a pirate",model="gpt-5.2",)robot_agent=pirate_agent.clone(name="Robot",instructions="Write like a robot",)

도구 사용 강제

도구 목록을 제공하더라도 LLM 이 항상 도구를 사용하는 것은 아닙니다.ModelSettings.tool_choice 를 설정하여 도구 사용을 강제할 수 있습니다. 유효한 값은 다음과 같습니다:

auto: LLM 이 도구 사용 여부를 스스로 결정
required: LLM 이 반드시 도구를 사용하도록 요구함(어떤 도구를 사용할지는 지능적으로 결정)
none: LLM 이 도구를사용하지 않도록 요구함
특정 문자열(예:my_tool)을 설정하여 LLM 이 그 특정 도구를 사용하도록 요구

fromagentsimportAgent,Runner,function_tool,ModelSettings@function_tooldefget_weather(city:str)->str:"""Returns weather info for the specified city."""returnf"The weather in{city} is sunny"agent=Agent(name="Weather Agent",instructions="Retrieve weather details.",tools=[get_weather],model_settings=ModelSettings(tool_choice="get_weather"))

도구 사용 동작

Agent 구성의tool_use_behavior 매개변수는 도구 출력 처리 방식을 제어합니다:

"run_llm_again": 기본값. 도구를 실행하고, LLM 이 결과를 처리해 최종 응답을 생성
"stop_on_first_tool": 첫 번째 도구 호출의 출력을 추가 LLM 처리 없이 최종 응답으로 사용

fromagentsimportAgent,Runner,function_tool,ModelSettings@function_tooldefget_weather(city:str)->str:"""Returns weather info for the specified city."""returnf"The weather in{city} is sunny"agent=Agent(name="Weather Agent",instructions="Retrieve weather details.",tools=[get_weather],tool_use_behavior="stop_on_first_tool")

StopAtTools(stop_at_tool_names=[...]): 지정된 도구 중 하나가 호출되면 중지하고, 해당 도구 출력을 최종 응답으로 사용

fromagentsimportAgent,Runner,function_toolfromagents.agentimportStopAtTools@function_tooldefget_weather(city:str)->str:"""Returns weather info for the specified city."""returnf"The weather in{city} is sunny"@function_tooldefsum_numbers(a:int,b:int)->int:"""Adds two numbers."""returna+bagent=Agent(name="Stop At Stock Agent",instructions="Get weather or sum numbers.",tools=[get_weather,sum_numbers],tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"]))

ToolsToFinalOutputFunction: 도구 결과를 처리하고 중지할지 LLM 을 계속 사용할지 결정하는 사용자 정의 함수

fromagentsimportAgent,Runner,function_tool,FunctionToolResult,RunContextWrapperfromagents.agentimportToolsToFinalOutputResultfromtypingimportList,Any@function_tooldefget_weather(city:str)->str:"""Returns weather info for the specified city."""returnf"The weather in{city} is sunny"defcustom_tool_handler(context:RunContextWrapper[Any],tool_results:List[FunctionToolResult])->ToolsToFinalOutputResult:"""Processes tool results to decide final output."""forresultintool_results:ifresult.outputand"sunny"inresult.output:returnToolsToFinalOutputResult(is_final_output=True,final_output=f"Final weather:{result.output}")returnToolsToFinalOutputResult(is_final_output=False,final_output=None)agent=Agent(name="Weather Agent",instructions="Retrieve weather details.",tools=[get_weather],tool_use_behavior=custom_tool_handler)