AI Agents

Orbit AI Agents are autonomous conversational agents that handle voice calls, chat messages, and multi-channel workflows without human intervention. Powered by LangGraph state machines and connected to your business tools, agents can qualify leads, handle support tickets, schedule appointments, and more.

How It Works

User Message → Orbit API → Agent Runtime → Anthropic Claude → Tool Calls → Response
                                ↓
                         State Graph (LangGraph)
                                ↓
                     Memory / Context / Tools

Inbound trigger — a user sends a message or calls a number routed to an agent
State evaluation — the agent runtime loads the conversation state and determines the next step
LLM reasoning — the agent sends conversation context to Anthropic’s Claude for a decision
Tool execution — the agent calls tools (APIs, databases, functions) as needed
Response — the agent replies to the user via the appropriate channel

Agent Types

The type field you set on create accepts one of the following values (default custom):

`type` value	Description
`custom`	General-purpose agent you configure from scratch (the default)
`chatbot`	Text-first conversational agent for support and FAQ flows
`router`	Classifies intent and routes the conversation to specialized agents via handoff targets
`voice`	Real-time phone conversations with STT/TTS
`workflow`	Orchestrates multi-step, tool-driven workflows

type is a behavioral hint for the agent runtime — it does not restrict channel reach. Which channels an agent can serve (voice, SMS, WhatsApp, RCS, etc.) is determined by how the agent is deployed and which channels you attach to it, not by the type value.

Deployment model

Channels are not set at create time — there is no channels field on the agent. Bind the agent to a channel with one deploy call per channel:

curl -X POST https://api.orbit.devotel.io/api/v1/agents/agent_xyz/deploy \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms", "phone_number": "+1..." }'

channel accepts exactly five values — an unknown value returns 422:

`channel`	What you send	Notes
`sms`	`phone_number`	The sending number inbound SMS routes to the agent.
`whatsapp`	WABA-linked destination	The WhatsApp Business account must be connected to your workspace first; the agent inherits its approved templates.
`rcs`	RCS sender	Requires a verified RCS sender on the workspace.
`voice`	Phone number to route	Voice-only knobs live under `voice_settings` on the agent (TTS provider/voice, barge-in, backchannel, STT keyterms). All fields are optional — absent values inherit the voice-gateway defaults.
`webhook`	`webhook_url`	Inbound agent turns POSTed to your endpoint.

One agent, several channels

Deploy to as many channels as you need — each deploy call adds one channel binding. Per-channel sessions are unified by default: cross_channel_enabled (default on create) lets the agent remember a contact’s earlier conversations on other channels, so an SMS + web-chat continuation shares context instead of starting cold. Set it to false to run each channel as an isolated session. For the conversation-side semantics (how the thread itself moves across channels while keeping one transcript), see Continue a conversation on another channel.

Channel restrictions to plan for

Voice — phone behavior (TTS voice, barge-in sensitivity, backchanneling, STT biasing) is configured on the agent’s voice_settings, not on the deploy call. Voice agents deploy and run with gateway defaults if you skip it, but tune before launch: Creating Agents → Deploy.
WhatsApp — deploy requires a WABA connection already linked to the workspace, and outbound template-initiated sends still need approved templates; the agent answers inside the 24-hour window or via templates.
Router agents — a router only hands work on; pair it with handoff targets and deploy the router itself on the inbound channel.

Limits and quotas

Hard caps enforced by the create/update schema and runtime:

Surface	Cap
`name`	100 characters
`description`	500 characters
`system_prompt`	10,000 characters
`max_tokens` per completion	32,000 (default 4,096)
`tools`	64 entries (bare string references or typed tool definitions)
`handoff_targets`	50 agent ids
`response_languages`	40 ISO 639-1 codes
Knowledge bases per agent	Bounded indirectly — the `search_knowledge` tool grounds only in attached bases; attach what the prompt actually needs.

Runtime budgets (per agent, all overridable on create/update):

Knob	Default	Behavior on breach
`max_cost_per_run_cents`	100 ($1.00)	The run aborts with `COST_LIMIT`.
`max_cost_per_conversation_cents`	none	Further LLM calls refused once the conversation crosses the cap.
`tool_loop_limit`	10	Hard ceiling 50; tool-calling turns stop at the limit.
`max_tokens_per_conversation`	10,000	Conversation terminates with `TOKEN_LIMIT`.
`latency_budget` (`ttft_ms`, `turn_ms`)	30-second turn	Per-turn latency targets for text agents; breaches surface in telemetry, not in the reply path.

Org-level invocation throttles return AGENT_INVOCATION_RATE_LIMIT_EXCEEDED (per-minute) and AGENT_INVOCATION_QUOTA_EXCEEDED (per-day, resets 00:00 UTC) as 429s — raise them via the agent rate-limits endpoints. There is no per-org cap on the number of agents.

Observability

Agent metrics surface in three places:

Analytics — resolution rates, latency, and cost per conversation are queried through the analytics surface; see Cross-channel analytics for the /api/v1/analytics endpoints (60 req/min/tenant, analytics:read scope).
Voice per-turn latency — for voice agents, GET /api/v1/voice/calls/:id/latency breaks a call down per turn (STT / LLM / TTS legs, P50/P95/P99) and per-turn cost (actual_cost_usd, billed_cost_usd).
Webhook events — agent lifecycle and handoff events are dispatched as agent.created, agent.updated, agent.deleted, agent.deployed, agent.undeployed, and agent.handoff_occurred. Subscribe from the webhook events catalog.

Cost uses two columns throughout agent surfaces: actual_cost_usd is the raw provider cost of the tokens an agent consumed; billed_cost_usd is what you are charged on your Devotel Orbit bill for the same work. Reconcile spend against billed_cost_usd; use actual_cost_usd only when comparing provider efficiency across models.

Handoff to humans and other agents

“Handoff” on this page means one of three supported moves — pick deliberately:

Pair	How it works	Guide
AI → human	`escalate_to_human` conditions on the agent hand the conversation to your inbox with full context. Voice escalations keep the call attached.	Creating Agents
Human → AI	Live calls can be handed back to the original voice agent after the human resolves their part.	Return an escalated call to the AI agent
AI → AI	Router-style agents hand off only to the targets on their `handoff_targets` allowlist.	Handoff targets

Limits choose the model

model is validated against an allowlist — anything else returns 422 with invalid_claude_model:

Model id	Use it for
`claude-sonnet-4-6`	Default. Tool calling + general conversations.
`claude-opus-4-7`	Deeper reasoning — orchestration, compliance, billing-sensitive flows.
`claude-opus-5`	Flagship tier; opt-in.
`claude-haiku-4-5-20251001`	Fast triage / classification. The dated snapshot only — the bare alias is rejected.
`claude-fable-5`	Vision-enabled agents (image input).

Model choice is a cost/lever: heavier models cost more per turn and can blow max_cost_per_run_cents faster; a cheaper model with a tightened tool_loop_limit often beats a heavy model on volume triage. See Model selection and Cost controls.

Create-an-agent checklist

Before you deploy, confirm:

Knowledge base ready — content ingested and attached via knowledge_base_ids; search_knowledge finds nothing without it. Knowledge base lifecycle
Tools mapped — each entry under 64, names snake_case, custom tools not shadowing built-ins. Creating Agents → Built-in tools
System prompt tested — under 10,000 characters, exercised against the dry-run / simulation endpoints before the first live deploy. Red-team and simulation guides
Toggles set deliberately — cross_channel_enabled, memory_enabled, vision_enabled, budgets, and tool_loop_limit — the schema defaults are sensible but they are your policy.
Handoff allowlisted — if the agent routes, handoff_targets names real agent ids. Handoff targets
Channel verified — sending number, WABA link, or SIP webhook reachable; then one deploy call per channel.

Common errors

Code	HTTP	Mean / fix
`VALIDATION_ERROR`	422	A field failed the create/update schema. Messages name the field (`model`, `tools`, …).
`invalid_claude_model`	422	`model` is not on the allowlist above — retry with an accepted id.
`INVALID_MODEL`	422	Same class from the service layer (duplicate/import paths): the id must be one of the valid models.
`INVALID_KNOWLEDGE_BASE_IDS`	422	At least one id in `knowledge_base_ids` doesn’t exist in your workspace — list ids in the error `message`.
`INVALID_HANDOFF_TARGETS`	422	A `handoff_targets` entry is not a real agent in your workspace.
`AGENT_NOT_CONFIGURED`	422	Deploy was attempted before the agent has a system prompt.
`AGENT_INVOCATION_RATE_LIMIT_EXCEEDED`	429	Per-minute org/agent invocation limit; retry shortly or raise the limit.
`AGENT_INVOCATION_QUOTA_EXCEEDED`	429	Per-day invocation quota exhausted; resets 00:00 UTC.
`AGENT_REFERENCED_BY_CHILD_ROWS` / `AGENT_REFERENCED_BY_SQUAD`	409	Delete blocked — remove deployments/squad membership first.

Quick Example

Create a simple FAQ agent with the Node.js SDK:

import { Devotel } from '@devotel-orbit/node';

const client = new Devotel({ apiKey: 'dv_live_sk_...' });

const agent = await client.agents.create({
  name: 'FAQ Bot',
  model: 'claude-sonnet-4-6',
  system_prompt: 'You are a helpful FAQ bot for Acme Corp. Answer questions about our products and services.',
  tools: ['search_knowledge'],
  knowledge_base_ids: ['kb_acme_faq'],
});

The search_knowledge built-in tool performs semantic retrieval, but it only grounds in content you attach via knowledge_base_ids. Without a linked knowledge base it has nothing to search. See the full built-in tool registry in Creating Agents.

Next Steps

Creating Agents — step-by-step setup guide
Model selection — pick the right Claude tier
Cost controls — per-agent spend and token caps
Handoff targets — multi-agent routing allowlist
Agent Marketplace — pre-built templates
Flows — connect agents to visual workflows

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

AI agents on Orbit: build, deploy, and monitor

AI Agents

How It Works

Agent Types

Deployment model

One agent, several channels

Channel restrictions to plan for

Limits and quotas

Observability

Handoff to humans and other agents

Limits choose the model

Create-an-agent checklist

Common errors

Quick Example

Next Steps

​AI Agents

​How It Works

​Agent Types

​Deployment model

​One agent, several channels

​Channel restrictions to plan for

​Limits and quotas

​Observability

​Handoff to humans and other agents

​Limits choose the model

​Create-an-agent checklist

​Common errors

​Quick Example

​Next Steps

AI Agents

How It Works

Agent Types

Deployment model

One agent, several channels

Channel restrictions to plan for

Limits and quotas

Observability

Handoff to humans and other agents

Limits choose the model

Create-an-agent checklist

Common errors

Quick Example

Next Steps