4142434445464748495051525354555657585960616263646566676869707172737475

@dataclass(frozen=True)classHandoffInputData:input_history:str|tuple[TResponseInputItem,...]"""    The input history before `Runner.run()` was called.    """pre_handoff_items:tuple[RunItem,...]"""    The items generated before the agent turn where the handoff was invoked.    """new_items:tuple[RunItem,...]"""    The new items generated during the current agent turn, including the item that triggered the    handoff and the tool output message representing the response from the handoff output.    """run_context:RunContextWrapper[Any]|None=None"""    The run context at the time the handoff was invoked. Note that, since this property was added    later on, it is optional for backwards compatibility.    """defclone(self,**kwargs:Any)->HandoffInputData:"""        Make a copy of the handoff input data, with the given arguments changed. For example, you        could do:        ```        new_handoff_input_data = handoff_input_data.clone(new_items=())        ```        """returndataclasses_replace(self,**kwargs)

 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155

@dataclassclassHandoff(Generic[TContext,TAgent]):"""A handoff is when an agent delegates a task to another agent.    For example, in a customer support scenario you might have a "triage agent" that determines    which agent should handle the user's request, and sub-agents that specialize in different areas    like billing, account management, etc.    """tool_name:str"""The name of the tool that represents the handoff."""tool_description:str"""The description of the tool that represents the handoff."""input_json_schema:dict[str,Any]"""The JSON schema for the handoff input. Can be empty if the handoff does not take an input."""on_invoke_handoff:Callable[[RunContextWrapper[Any],str],Awaitable[TAgent]]"""The function that invokes the handoff.    The parameters passed are: (1) the handoff run context, (2) the arguments from the LLM as a    JSON string (or an empty string if ``input_json_schema`` is empty). Must return an agent.    """agent_name:str"""The name of the agent that is being handed off to."""input_filter:HandoffInputFilter|None=None"""A function that filters the inputs that are passed to the next agent.    By default, the new agent sees the entire conversation history. In some cases, you may want to    filter inputs (for example, to remove older inputs or remove tools from existing inputs). The    function receives the entire conversation history so far, including the input item that    triggered the handoff and a tool call output item representing the handoff tool's output. You    are free to modify the input history or new items as you see fit. The next agent that runs will    receive ``handoff_input_data.all_items``. IMPORTANT: in streaming mode, we will not stream    anything as a result of this function. The items generated before will already have been    streamed.    """nest_handoff_history:bool|None=None"""Override the run-level ``nest_handoff_history`` behavior for this handoff only."""strict_json_schema:bool=True"""Whether the input JSON schema is in strict mode. We strongly recommend setting this to True    because it increases the likelihood of correct JSON input."""is_enabled:bool|Callable[[RunContextWrapper[Any],AgentBase[Any]],MaybeAwaitable[bool]]=(True)"""Whether the handoff is enabled.    Either a bool or a callable that takes the run context and agent and returns whether the    handoff is enabled. You can use this to dynamically enable or disable a handoff based on your    context or state.    """defget_transfer_message(self,agent:AgentBase[Any])->str:returnjson.dumps({"assistant":agent.name})@classmethoddefdefault_tool_name(cls,agent:AgentBase[Any])->str:return_transforms.transform_string_function_style(f"transfer_to_{agent.name}")@classmethoddefdefault_tool_description(cls,agent:AgentBase[Any])->str:return(f"Handoff to the{agent.name} agent to handle the request. "f"{agent.handoff_descriptionor''}")

90919293949596

defdefault_handoff_history_mapper(transcript:list[TResponseInputItem],)->list[TResponseInputItem]:"""Return a single assistant message summarizing the transcript."""summary_message=_build_summary_message(transcript)return[summary_message]

55565758

defget_conversation_history_wrappers()->tuple[str,str]:"""Return the current start/end markers used for the nested conversation summary."""return(_conversation_history_start,_conversation_history_end)

616263646566676869707172737475767778798081828384858687

defnest_handoff_history(handoff_input_data:HandoffInputData,*,history_mapper:HandoffHistoryMapper|None=None,)->HandoffInputData:"""Summarize the previous transcript for the next agent."""normalized_history=_normalize_input_history(handoff_input_data.input_history)flattened_history=_flatten_nested_history_messages(normalized_history)pre_items_as_inputs=[_run_item_to_plain_input(item)foriteminhandoff_input_data.pre_handoff_items]new_items_as_inputs=[_run_item_to_plain_input(item)foriteminhandoff_input_data.new_items]transcript=flattened_history+pre_items_as_inputs+new_items_as_inputsmapper=history_mapperordefault_handoff_history_mapperhistory_items=mapper(transcript)filtered_pre_items=tuple(itemforiteminhandoff_input_data.pre_handoff_itemsif_get_run_item_role(item)!="assistant")returnhandoff_input_data.clone(input_history=tuple(deepcopy(item)foriteminhistory_items),pre_handoff_items=filtered_pre_items,)

474849505152

defreset_conversation_history_wrappers()->None:"""Restore the default ``<CONVERSATION HISTORY>`` markers."""global_conversation_history_start,_conversation_history_end_conversation_history_start=_DEFAULT_CONVERSATION_HISTORY_START_conversation_history_end=_DEFAULT_CONVERSATION_HISTORY_END

303132333435363738394041424344

defset_conversation_history_wrappers(*,start:str|None=None,end:str|None=None,)->None:"""Override the markers that wrap the generated conversation summary.    Pass ``None`` to leave either side unchanged.    """global_conversation_history_start,_conversation_history_endifstartisnotNone:_conversation_history_start=startifendisnotNone:_conversation_history_end=end

197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304

defhandoff(agent:Agent[TContext],tool_name_override:str|None=None,tool_description_override:str|None=None,on_handoff:OnHandoffWithInput[THandoffInput]|OnHandoffWithoutInput|None=None,input_type:type[THandoffInput]|None=None,input_filter:Callable[[HandoffInputData],HandoffInputData]|None=None,nest_handoff_history:bool|None=None,is_enabled:bool|Callable[[RunContextWrapper[Any],Agent[TContext]],MaybeAwaitable[bool]]=True,)->Handoff[TContext,Agent[TContext]]:"""Create a handoff from an agent.    Args:        agent: The agent to handoff to.        tool_name_override: Optional override for the name of the tool that represents the handoff.        tool_description_override: Optional override for the description of the tool that            represents the handoff.        on_handoff: A function that runs when the handoff is invoked.        input_type: The type of the input to the handoff. If provided, the input will be validated            against this type. Only relevant if you pass a function that takes an input.        input_filter: A function that filters the inputs that are passed to the next agent.        nest_handoff_history: Optional override for the RunConfig-level ``nest_handoff_history``            flag. If ``None`` we fall back to the run's configuration.        is_enabled: Whether the handoff is enabled. Can be a bool or a callable that takes the run            context and agent and returns whether the handoff is enabled. Disabled handoffs are            hidden from the LLM at runtime.    """assert(on_handoffandinput_type)ornot(on_handoffandinput_type),("You must provide either both on_handoff and input_type, or neither")type_adapter:TypeAdapter[Any]|Noneifinput_typeisnotNone:assertcallable(on_handoff),"on_handoff must be callable"sig=inspect.signature(on_handoff)iflen(sig.parameters)!=2:raiseUserError("on_handoff must take two arguments: context and input")type_adapter=TypeAdapter(input_type)input_json_schema=type_adapter.json_schema()else:type_adapter=Noneinput_json_schema={}ifon_handoffisnotNone:sig=inspect.signature(on_handoff)iflen(sig.parameters)!=1:raiseUserError("on_handoff must take one argument: context")asyncdef_invoke_handoff(ctx:RunContextWrapper[Any],input_json:str|None=None)->Agent[TContext]:ifinput_typeisnotNoneandtype_adapterisnotNone:ifinput_jsonisNone:_error_tracing.attach_error_to_current_span(SpanError(message="Handoff function expected non-null input, but got None",data={"details":"input_json is None"},))raiseModelBehaviorError("Handoff function expected non-null input, but got None")validated_input=_json.validate_json(json_str=input_json,type_adapter=type_adapter,partial=False,)input_func=cast(OnHandoffWithInput[THandoffInput],on_handoff)ifinspect.iscoroutinefunction(input_func):awaitinput_func(ctx,validated_input)else:input_func(ctx,validated_input)elifon_handoffisnotNone:no_input_func=cast(OnHandoffWithoutInput,on_handoff)ifinspect.iscoroutinefunction(no_input_func):awaitno_input_func(ctx)else:no_input_func(ctx)returnagenttool_name=tool_name_overrideorHandoff.default_tool_name(agent)tool_description=tool_description_overrideorHandoff.default_tool_description(agent)# Always ensure the input JSON schema is in strict mode. If needed, we can make this# configurable in the future.input_json_schema=ensure_strict_json_schema(input_json_schema)asyncdef_is_enabled(ctx:RunContextWrapper[Any],agent_base:AgentBase[Any])->bool:from..agentimportAgentassertcallable(is_enabled),"is_enabled must be callable here"assertisinstance(agent_base,Agent),"Can't handoff to a non-Agent"result=is_enabled(ctx,agent_base)ifinspect.isawaitable(result):returnawaitresultreturnbool(result)returnHandoff(tool_name=tool_name,tool_description=tool_description,input_json_schema=input_json_schema,on_invoke_handoff=_invoke_handoff,input_filter=input_filter,nest_handoff_history=nest_handoff_history,agent_name=agent.name,is_enabled=_is_enabledifcallable(is_enabled)elseis_enabled,)