Skip to main content

​
Creating Agents

This guide walks you through creating, configuring, and deploying an AI agent on Orbit — from defining its behavior to connecting it to live channels.

​
Step 1: Define the Agent

Create an agent with a name, instructions, and model selection. 
curl -X POST https://orbit-api.devotel.io/api/v1/agents \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Handles customer support inquiries for Acme Corp",
    "model": "gpt-4o",
    "instructions": "You are a customer support agent for Acme Corp. Be helpful, concise, and professional. If you cannot resolve an issue, offer to transfer to a human agent.",
    "temperature": 0.3
  }'

​
Step 2: Add Tools

Tools give your agent the ability to take actions — look up orders, create tickets, check inventory, etc. 
curl -X POST https://orbit-api.devotel.io/api/v1/agents/agent_abc123/tools \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lookup_order",
    "description": "Look up an order by order ID or customer email",
    "type": "api",
    "endpoint": "https://api.acme.com/orders/search",
    "method": "GET",
    "parameters": {
      "order_id": { "type": "string", "description": "The order ID" },
      "email": { "type": "string", "description": "Customer email address" }
    }
  }'

​
Built-in Tools

Orbit provides several built-in tools that agents can use out of the box:
ToolDescription
knowledge_baseSearch uploaded documents and FAQs
human_handoffTransfer conversation to a human agent
send_messageSend a message on any channel
schedule_callbackSchedule a follow-up call or message
collect_paymentCollect payment via a secure link

​
Step 3: Connect Knowledge Base

Upload documents for your agent to reference during conversations. 
curl -X POST https://orbit-api.devotel.io/api/v1/agents/agent_abc123/knowledge \
  -H "X-API-Key: dv_live_sk_..." \
  -F "file=@faq.pdf" \
  -F "type=pdf"
Orbit chunks, embeds (via OpenAI text-embedding-3-large), and indexes documents in Qdrant for fast retrieval.

​
Step 4: Assign Channels

Connect your agent to one or more communication channels. 
curl -X PATCH https://orbit-api.devotel.io/api/v1/agents/agent_abc123 \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channels": [
      { "type": "sms", "phone_number": "+18005551234" },
      { "type": "whatsapp", "phone_number": "+18005551234" },
      { "type": "voice", "phone_number": "+18005551234" }
    ]
  }'

​
Step 5: Configure Guardrails

Set safety boundaries for your agent’s behavior. 
curl -X PATCH https://orbit-api.devotel.io/api/v1/agents/agent_abc123/guardrails \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "pii_redaction": true,
    "content_filter": true,
    "max_turns": 50,
    "escalation_keywords": ["speak to human", "manager", "complaint"],
    "blocked_topics": ["competitor pricing", "internal processes"]
  }'

​
Step 6: Deploy

Activate your agent to start handling live conversations. 
curl -X POST https://orbit-api.devotel.io/api/v1/agents/agent_abc123/deploy \
  -H "X-API-Key: dv_live_sk_..."

​
Testing

Test your agent before going live using the sandbox endpoint: 
curl -X POST https://orbit-api.devotel.io/api/v1/agents/agent_abc123/test \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hi, I need help with order ORD-12345"
  }'
The test endpoint simulates a conversation without sending real messages or incurring channel costs.