​

Agent handoff targets

​

What it gates

1. Runtime — the transfer_to_agent tool is always registered, so the LLM always sees it in its tool list. The allowlist is checked inside the tool handler after the model calls it: if target_agent_id is not on the source agent’s allowlist (or the allowlist is empty), the call returns an error result and no handoff occurs. The model receives that error and continues the turn — it does not crash the conversation.
2. Internal handoff API (POST /api/v1/agents/internal/handoffs) — even with a valid internal token, a handoff is rejected with 403 FORBIDDEN if the target is not on the source agent’s allowlist. This protects the audit ledger and the agent.handoff_occurred webhook from forged entries.

​

Configure on agent create

curl -X POST https://api.orbit.devotel.io/api/v1/agents \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Triage Router",
    "description": "Classifies inbound messages and routes to a specialist.",
    "model": "claude-sonnet-4-6",
    "system_prompt": "You are a customer service router for Acme Corp. Classify the inbound message and use transfer_to_agent to hand off to the right specialist.",
    "handoff_targets": [
      "agent_billing_specialist",
      "agent_support_specialist",
      "agent_returns_specialist"
    ]
  }'

​

Configure on agent update

curl -X PUT https://api.orbit.devotel.io/api/v1/agents/agent_router \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "handoff_targets": [
      "agent_billing_specialist",
      "agent_support_specialist"
    ]
  }'

​

Update semantics

​

What a runtime handoff looks like

1. Persists an agent_handoffs row.
2. Fans out a webhook event agent.handoff_occurred to the tenant’s subscription endpoint with handoff_id, source_agent_id, target_agent_id, conversation_id, reason, and summary.
3. Re-enters the runtime with the target agent’s executor, carrying the conversation history forward.

​

What a refused handoff looks like

{
  "error": "HANDOFF_TARGET_NOT_ALLOWED",
  "message": "Agent agent_unknown is not in your handoff_targets allowlist."
}

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "code": "FORBIDDEN",
    "message": "The target agent is not on the source agent's handoff_targets allowlist.",
    "status": 403
  }
}

​

Patterns

​

One-way fan-out (router → specialists)

agent_router.handoff_targets = [agent_billing, agent_support, agent_returns]
agent_billing.handoff_targets   = []   # specialists do not re-route
agent_support.handoff_targets   = []
agent_returns.handoff_targets   = []

​

Two-way (specialists can return to router)

agent_router.handoff_targets    = [agent_billing, agent_support]
agent_billing.handoff_targets   = [agent_router]
agent_support.handoff_targets   = [agent_router]

​

Mesh

agent_billing.handoff_targets = [agent_support]
agent_support.handoff_targets = [agent_billing]

​

Common pitfalls

• Forgetting to set handoff_targets — the model still sees the transfer_to_agent tool (it is always registered) and may try to use it, but every call is rejected by the runtime because the allowlist is empty. Symptom: the agent keeps trying to hand off and gets HANDOFF_TARGET_NOT_ALLOWED back, then answers itself anyway. Set the allowlist to make the handoff actually route.
• Listing an agent that doesn’t exist — PUT /api/v1/agents/:id validates every supplied id against the tenant’s existing agents and rejects the whole request with 422 INVALID_HANDOFF_TARGETS if any id is missing (the response message lists the offending ids). The only case in which an unknown target is a harmless runtime no-op is one that was already persisted before the agent it pointed at was deleted — transfer_to_agent then simply can’t route to it. Note the create/update asymmetry: POST /api/v1/agents does not run this existence check, so a create call can persist an unknown id that a later PUT would reject.
• Listing the agent’s own id — allowed but pointless. The runtime handles transfer_to_agent with the same agent as a no-op.
• Cross-tenant ids — every id is tenant-scoped. You cannot hand off to an agent in a different organisation.

​

See also

• Creating Agents — full agent-create reference.
• Cost controls — max_cost_per_run_cents / max_cost_per_conversation_cents.
• Webhooks → Events — agent.handoff_occurred payload.