Codex.Handoff (Codex SDK v0.7.2)

Represents a handoff from one agent to another, wrapping the downstream agent as a tool with optional input filtering and history nesting controls.

Summary

Types

is_enabled()

t()

Functions

default_tool_description(agent)

Default tool description referencing the downstream agent.

default_tool_name(agent)

Default tool name derived from the downstream agent name.

enabled?(handoff, context, agent)

Evaluates whether a handoff is enabled for the given context/agent.

wrap(agent, opts \\ [])

Wraps an agent as a handoff with optional overrides.

Types

is_enabled()

@type is_enabled() :: boolean() | (map(), Codex.Agent.t() -> boolean() | term())

t()

@type t() :: %Codex.Handoff{
  agent: Codex.Agent.t() | nil,
  agent_name: String.t(),
  input_filter:
    (Codex.Handoff.InputData.t() -> Codex.Handoff.InputData.t()) | nil,
  input_schema: map(),
  is_enabled: is_enabled(),
  nest_handoff_history: boolean() | nil,
  on_invoke_handoff: (map(), term() -> Codex.Agent.t()),
  strict_json_schema: boolean(),
  tool_description: String.t(),
  tool_name: String.t()
}

Functions

default_tool_description(agent)

@spec default_tool_description(Codex.Agent.t()) :: String.t()

Default tool description referencing the downstream agent.

default_tool_name(agent)

@spec default_tool_name(Codex.Agent.t()) :: String.t()

Default tool name derived from the downstream agent name.

enabled?(handoff, context, agent)

@spec enabled?(t(), map(), Codex.Agent.t()) :: boolean()

Evaluates whether a handoff is enabled for the given context/agent.

wrap(agent, opts \\ [])

@spec wrap(
  Codex.Agent.t(),
  keyword()
) :: t()

Wraps an agent as a handoff with optional overrides.

Options:

:tool_name - override the default tool name
:tool_description - override the default tool description
:input_filter - function invoked to filter history passed to the downstream agent
:nest_handoff_history - override history nesting behaviour
:input_schema - optional JSON schema map describing expected input
:strict_json_schema - whether the schema should be treated as strict (default: true)
:is_enabled - boolean or function to dynamically enable the handoff