SIPHON logo

Metadata & Routing

Metadata & Routing

SIPHON uses metadata to carry call context into your agent worker, and uses routing to decide which agent should receive a call.

This page stays conceptual (no deep code), and points you to the API pages for practical setup.

What is metadata?

Metadata is a dictionary attached to the call/job that can include:

  • Call direction (inbound/outbound)
  • Phone numbers involved in the call
  • Trunk identifiers
  • Agent configuration overrides (LLM/STT/TTS and instructions)

The worker reads this metadata when it starts a call session.

Routing: selecting an agent

Routing is the act of mapping a call to an agent_name.

  • Inbound routing is handled by dispatch rules (think: “if someone calls this number, send it to this agent”).
  • Outbound routing is created by your code when you place a call (SIPHON creates an agent dispatch for the agent_name you specify).

Why agent_name matters

An agent_name is the stable join point between:

  • the agent worker you run (Agent(agent_name=...))
  • the dispatch/call that routes calls (Dispatch(agent_name=...) / Call(agent_name=...))

If these don’t match, the call can be created, but your worker will not pick up the job.

Dynamic configuration (per-call overrides)

SIPHON supports two complementary configuration layers:

  • Worker defaults
    • The baseline behavior configured when you start the worker.
  • Per-call overrides
    • Optional overrides passed via Dispatch(...) or Call(...) so a single worker can behave differently per call.

Common overrides:

  • llm, stt, tts
  • system_instructions, greeting_instructions

This is useful when:

  • the same agent should speak differently based on the number dialed
  • you want to personalize the agent with customer metadata
  • you want to run many “micro-agents” without starting many worker processes

Where to learn the practical setup

Next