Handoff Agent

📸 Screenshots

Here are visual examples of this section:

Handoff Agent - Worker Configuration Interface

The Handoff Agent is a specialized worker designed to manage agent handoffs and routing within complex workflows. It creates an OpenAI agent that can receive handoff requests, execute tools, and route conversations to appropriate agents based on handoff descriptions. This worker is particularly useful for orchestrating multi-agent conversations and ensuring smooth transitions between different specialized agents.

2. Configuration Parameters

handoffDescription: Optional description that defines when and how this agent should receive handoffs from other agents
model: The AI model to use for the agent, defaults to "openai/gpt-4.1"

3. Input/Output Handles

instructions: Input handle - accepts string instructions that guide the agent's behavior
handoff: Input handle - accepts handoff requests from other agents
tool: Output handle - provides tool functionality to connected workers

4. Usage Examples with Code

// Create a handoff agent with custom instructions and model
const handoffAgent = {
  type: "handoffAgent",
  parameters: {
    handoffDescription: "Customer service specialist for billing inquiries",
    model: "openai/gpt-4.1"
  },
  fields: {
    instructions: "You are a helpful customer service agent specializing in billing issues.",
    handoff: connectedHandoffSource,
    tool: connectedToolWorkers
  }
}

5. Integration Examples

The Handoff Agent works best in multi-agent workflows where different agents need to collaborate and hand off conversations based on expertise or context. It can be connected to various tool workers to provide specialized functionality during handoff scenarios.

6. Best Practices

Provide clear and specific handoff descriptions to ensure proper routing
Use descriptive instructions that align with the agent's intended role
Connect relevant tool workers to give the agent necessary capabilities
Monitor handoff events through the built-in logging system

7. Troubleshooting Tips

Ensure connected tool workers have proper tool descriptions set
Verify API keys are properly configured for the selected model
Check that handoff descriptions are specific enough to avoid routing conflicts
Review agent logs for handoff, tool_start, and tool_end events to debug workflow issues