Agents API

Build AI-powered conversational and task agents. Create agents with custom tools and guardrails, deploy them to messaging and voice channels, run conversations programmatically, and access interaction history. Base path: /v1/agents

CRUD Operations

Create Agent

POST /v1/agents

name

string

required

Agent display name

type

string

required

Agent type: conversational or task

model

string

required

LLM model to use (e.g., gpt-4o, claude-sonnet-4-20250514, gemini-2.0-flash)

system_prompt

string

required

System instructions that define the agent’s behavior and personality

tools

object[]

Tool definitions the agent can invoke

Show child attributes

tools[].name

string

required

Tool name

tools[].description

string

What the tool does

tools[].parameters

object

JSON Schema of input parameters

channels

string[]

Channels this agent is available on: whatsapp, sms, voice, web

guardrails

object

Portkey guardrail configuration for output validation

Show child attributes

guardrails.input_checks

string[]

Input validation rules

guardrails.output_checks

string[]

Output validation rules

knowledge_base_ids

string[]

IDs of knowledge bases (Qdrant collections) to attach for RAG

temperature

number

default:"0.7"

LLM temperature (0.0–2.0)

max_tokens

integer

default:"4096"

Maximum tokens per LLM response

curl -X POST https://orbit-api.devotel.io/api/v1/agents \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "type": "conversational",
    "model": "gpt-4o",
    "system_prompt": "You are a helpful customer support agent for Acme Corp.",
    "channels": ["whatsapp", "web"],
    "tools": [
      {
        "name": "lookup_order",
        "description": "Look up order details by order ID",
        "parameters": {
          "type": "object",
          "properties": { "order_id": { "type": "string" } },
          "required": ["order_id"]
        }
      }
    ],
    "guardrails": {
      "output_checks": ["no_pii", "no_profanity", "brand_voice"]
    },
    "temperature": 0.5
  }'

{
  "data": {
    "id": "agt_abc123",
    "name": "Support Bot",
    "type": "conversational",
    "model": "gpt-4o",
    "status": "draft",
    "channels": ["whatsapp", "web"],
    "tools_count": 1,
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_agt_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

List Agents

GET /v1/agents Retrieve all agents with cursor-based pagination.

cursor

string

Cursor for pagination

limit

integer

default:"20"

Results per page (max 100)

status

string

Filter by status: draft, active, paused

Get Agent

GET /v1/agents/{id} Retrieve full configuration of an agent including tools, guardrails, and deployment status.

Update Agent

PUT /v1/agents/{id} Update an agent’s configuration. Changes take effect for new conversations immediately.

Delete Agent

DELETE /v1/agents/{id} Delete an agent. Active conversations are terminated gracefully. Response: 204 No Content

Deploy

Deploy Agent

POST /v1/agents/{id}/deploy Activate an agent and make it available on its configured channels. The agent must have a valid system_prompt and at least one channel configured.

string

required

Agent ID

channels

string[]

Override which channels to deploy to (defaults to agent’s configured channels)

number_id

string

Phone number ID to bind the agent to for voice and SMS

curl -X POST https://orbit-api.devotel.io/api/v1/agents/agt_abc123/deploy \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channels": ["whatsapp", "voice"],
    "number_id": "num_xyz789"
  }'

{
  "data": {
    "id": "agt_abc123",
    "status": "active",
    "deployed_channels": ["whatsapp", "voice"],
    "bound_number": "+14155550100",
    "deployed_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_deploy_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Pause Agent

POST /v1/agents/{id}/pause Temporarily deactivate an agent. Existing conversations are completed but no new ones are started.

Resume Agent

POST /v1/agents/{id}/resume Re-activate a paused agent.

Chat

Send Chat Message

POST /v1/agents/{id}/chat Send a message to an agent and receive a response. Supports both stateless single-turn and stateful multi-turn conversations.

string

required

Agent ID

message

string

required

User message text

conversation_id

string

Existing conversation ID for multi-turn. Omit to start a new conversation.

context

object

Additional context variables to inject (e.g., user profile, order data)

stream

boolean

default:"false"

Stream the response as Server-Sent Events

curl -X POST https://orbit-api.devotel.io/api/v1/agents/agt_abc123/chat \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the status of order ORD-12345?",
    "context": {
      "customer_name": "Jane Doe",
      "customer_id": "cust_xyz"
    }
  }'

{
  "data": {
    "conversation_id": "conv_abc123",
    "message_id": "amsg_001",
    "role": "assistant",
    "content": "Hi Jane! I found your order ORD-12345. It was shipped yesterday via FedEx and is expected to arrive by March 10th. The tracking number is FX-987654321.",
    "tool_calls": [
      {
        "tool": "lookup_order",
        "input": { "order_id": "ORD-12345" },
        "output": { "status": "shipped", "carrier": "FedEx", "eta": "2026-03-10" }
      }
    ],
    "tokens_used": { "input": 245, "output": 62 },
    "latency_ms": 1840
  },
  "meta": {
    "request_id": "req_chat_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Streaming Responses

Set stream: true to receive the response as Server-Sent Events (SSE). Each chunk is a JSON object:

event: chunk
data: {"content": "Hi Jane! I found your "}

event: chunk
data: {"content": "order ORD-12345. "}

event: tool_call
data: {"tool": "lookup_order", "input": {"order_id": "ORD-12345"}}

event: tool_result
data: {"tool": "lookup_order", "output": {"status": "shipped"}}

event: chunk
data: {"content": "It was shipped yesterday..."}

event: done
data: {"conversation_id": "conv_abc123", "tokens_used": {"input": 245, "output": 62}}

Conversations

List Conversations

GET /v1/agents/{id}/conversations Retrieve conversation history for an agent.

cursor

string

Cursor for pagination

limit

integer

default:"20"

Results per page (max 100)

status

string

Filter: active, completed, abandoned

Get Conversation Messages

GET /v1/agents/{id}/conversations/{conversationId}/messages Retrieve the full message history of a specific conversation.

{
  "data": [
    {
      "id": "amsg_001",
      "role": "user",
      "content": "What is the status of order ORD-12345?",
      "created_at": "2026-03-08T12:00:00Z"
    },
    {
      "id": "amsg_002",
      "role": "assistant",
      "content": "Hi Jane! Your order ORD-12345 was shipped yesterday via FedEx.",
      "tool_calls": [
        { "tool": "lookup_order", "input": { "order_id": "ORD-12345" } }
      ],
      "created_at": "2026-03-08T12:00:02Z"
    },
    {
      "id": "amsg_003",
      "role": "user",
      "content": "Great, thanks!",
      "created_at": "2026-03-08T12:00:15Z"
    }
  ],
  "meta": {
    "request_id": "req_msgs_001",
    "timestamp": "2026-03-08T12:01:00Z",
    "pagination": {
      "cursor": "cur_amsg_003",
      "has_more": false,
      "total": 3
    }
  }
}

Agent Statuses

Status	Description
`draft`	Agent created but not yet deployed
`active`	Agent is live and accepting conversations
`paused`	Agent is temporarily deactivated
`error`	Agent encountered a configuration error

Examples

Node.js

const orbit = new Devotel({ apiKey: 'dv_live_sk_xxxx' })

const agent = await orbit.agents.create({
  name: 'Support Bot',
  type: 'conversational',
  model: 'gpt-4o',
  systemPrompt: 'You are a helpful support agent.',
  channels: ['web', 'whatsapp'],
})

await orbit.agents.deploy(agent.data.id)

const response = await orbit.agents.chat(agent.data.id, {
  message: 'Hello, I need help with my order.',
})

console.log(response.data.content)

Python

orbit = OrbitClient(api_key="dv_live_sk_xxxx")

agent = orbit.agents.create(
    name="Support Bot",
    type="conversational",
    model="gpt-4o",
    system_prompt="You are a helpful support agent.",
    channels=["web", "whatsapp"],
)

orbit.agents.deploy(agent.data.id)

response = orbit.agents.chat(
    agent.data.id,
    message="Hello, I need help with my order.",
)

print(response.data.content)

API Reference

​Agents API

​CRUD Operations

​Create Agent

​List Agents

​Get Agent

​Update Agent

​Delete Agent

​Deploy

​Deploy Agent

​Pause Agent

​Resume Agent

​Chat

​Send Chat Message

​Streaming Responses

​Conversations

​List Conversations

​Get Conversation Messages

​Agent Statuses

​Examples

​Node.js

​Python

Agents API

CRUD Operations

Create Agent

List Agents

Get Agent

Update Agent

Delete Agent

Deploy

Deploy Agent

Pause Agent

Resume Agent

Chat

Send Chat Message

Streaming Responses

Conversations

List Conversations

Get Conversation Messages

Agent Statuses

Examples

Node.js

Python