add-tools-and-handoffs

Add tools and handoffs to a Patter agent

Patter agents have two built-in tools (transfer_call, end_call) plus unlimited custom tools. Custom tools can be handler-based (your Python/TS function runs in-process) or webhook-based (the agent POSTs JSON arguments to your URL). Both shapes use the same Tool model. Output guardrails block or rephrase agent responses before they reach TTS.

Built-in tools (always available)

Every agent automatically has:

• transfer_call(target: str) — bridge to another phone number. Caller hears the new party, your Patter session ends.
• end_call() — hang up. Use for "goodbye" flows or abusive callers.

You don't have to register these. The LLM picks them when the system prompt authorizes it.

agent = phone.agent(
    engine=OpenAIRealtime2(),
    system_prompt=(
        "You are Mia, the receptionist for Acme. "
        "If the caller asks for a human, call `transfer_call` with target='+14155559999'. "
        "If the caller wants to hang up, call `end_call`."
    ),
    first_message="Hi, how can I help?",
)

Custom tools — handler form

The @tool decorator (Python) and defineTool (TypeScript) auto-extract the JSON schema from your function signature and docstring. Best for simple synchronous lookups.

Python

from getpatter import Patter, Twilio, OpenAIRealtime2, tool

@tool
async def lookup_customer(phone: str) -> dict:
    """Look up customer details by phone number.

    Args:
        phone: E.164 phone number, e.g. +14155551234.

    Returns:
        Customer name, tier, and last order date.
    """
    # your CRM call here
    return {"name": "Jane Doe", "tier": "gold", "last_order": "2026-04-12"}

phone = Patter(carrier=Twilio(), phone_number="+15550001234")
agent = phone.agent(
    engine=OpenAIRealtime2(),
    system_prompt="You are a customer-service agent. Use `lookup_customer` when you need account info.",
    first_message="Hi, can I help with your account?",
    tools=[lookup_customer],
)