> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Typed Handoff • AI Agent SDK

> TypedHandoff: Typed handoff with schema validation using Pydantic models.

# TypedHandoff

> Defined in the [**handoff**](../modules/handoff) module.

<Badge color="blue">AI Agent</Badge>

Typed handoff with schema validation using Pydantic models.

This class extends the base Handoff to add type safety through Pydantic schema validation.
The sender declares an output schema, the receiver expects that schema, and the framework
validates the payload at the boundary, raising HandoffValidationError if validation fails.

The receiving agent's prompt is constructed from validated JSON rather than raw string
concatenation, enabling proper deserialization of structured data.

## Constructor

<ParamField query="agent" type="Agent" required={true}>
  No description available.
</ParamField>

<ParamField query="input_schema" type="Type[T]" required={true}>
  No description available.
</ParamField>

<ParamField query="tool_name_override" type="Optional[str]" required={false}>
  No description available.
</ParamField>

<ParamField query="tool_description_override" type="Optional[str]" required={false}>
  No description available.
</ParamField>

<ParamField query="on_handoff" type="Optional[Callable]" required={false}>
  No description available.
</ParamField>

<ParamField query="input_filter" type="Optional" required={false}>
  No description available.
</ParamField>

<ParamField query="config" type="Optional[HandoffConfig]" required={false}>
  No description available.
</ParamField>

## Methods

<CardGroup cols={2}>
  <Card title="execute_programmatic()" icon="function" href="../functions/TypedHandoff-execute_programmatic">
    Execute typed handoff programmatically with schema validation.
  </Card>

  <Card title="execute_async()" icon="function" href="../functions/TypedHandoff-execute_async">
    Execute typed handoff asynchronously with schema validation.
  </Card>
</CardGroup>

## Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from pydantic import BaseModel
    from praisonaiagents.agent.handoff import TypedHandoff, HandoffValidationError
    
    class ResearchResult(BaseModel):
        summary: str
        citations: list[str] 
        confidence: float
        
    # Create typed handoff
    typed_handoff = TypedHandoff(
        agent=writer_agent,
        input_schema=ResearchResult
    )
    
    # Valid payload
    result = ResearchResult(
        summary="AI research findings", 
        citations=["ref1", "ref2"], 
        confidence=0.92
    )
    response = typed_handoff.execute_programmatic(source_agent, result)
    
    # Invalid payload raises HandoffValidationError
    bad_payload = {"summary": "...", "citations": "not-a-list"}
    typed_handoff.execute_programmatic(source_agent, bad_payload)  # Raises error
```

## Source

<Card title="View on GitHub" icon="github" href="https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agent/handoff.py#L1289">
  `praisonaiagents/agent/handoff.py` at line 1289
</Card>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Handoffs Concept" icon="hand-holding" href="/docs/docs/concepts/handoffs" />

  <Card title="Handoffs Feature" icon="arrow-right-arrow-left" href="/docs/docs/features/handoffs" />
</CardGroup>