Creating Agents

Step-by-step guide to building and deploying AI agents on Orbit

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:

Tool	Description
knowledge_base	Search uploaded documents and FAQs
human_handoff	Transfer conversation to a human agent
send_message	Send a message on any channel
schedule_callback	Schedule a follow-up call or message
collect_payment	Collect 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": "[phone]" },
      { "type": "whatsapp", "phone_number": "[phone]" },
      { "type": "voice", "phone_number": "[phone]" }
    ]
  }'

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.