Orbitali Docs

Create an HTTP Agent

Connect saved agent instructions to direct HTTP API actions.

An HTTP agent uses saved instructions and calls the endpoint configured on each custom tool. You do not need an Orbitali webhook handler or an agent Server URL.

1. Create the agent

In Agents → Create Agent, choose HTTP, then configure identity, instructions, voice, and greeting. Alternatively use Create with AI, which creates HTTP agents.

For API creation, use the complete request in API Getting Started with agentType: "http". Keep promptType: "static" and serverUrl: null. Save the returned ID as AGENT_ID.

2. Add an action

This example assumes you own a reachable HTTPS endpoint that returns order status. Replace the example URL with your endpoint before testing. The agent should ask for an order ID before calling this tool.

curl --fail-with-body "https://api.orbitali.ai/public/v1/agents/$AGENT_ID/tools" \
  -X POST \
  -H "Authorization: Bearer $ORBITALI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lookup_order",
    "description": "Look up an order status after the caller provides the order ID.",
    "parameterSchema": {
      "type": "object",
      "properties": { "orderId": { "type": "string" } },
      "required": ["orderId"]
    },
    "responseSchema": null,
    "timeoutMs": 5000,
    "onError": "return_error",
    "enabled": true,
    "toolUrl": "https://api.example.com/orders/status",
    "toolMethod": "GET",
    "toolHeaders": {},
    "toolStaticParams": {},
    "toolRuntimeMetadata": []
  }'

Success returns 201 with { "id": "<tool UUID>" }. For arguments { "orderId": "DEMO-123" }, Orbitali requests GET https://api.example.com/orders/status?orderId=DEMO-123. Return a concise response such as:

{ "orderId": "DEMO-123", "status": "shipped" }

For POST and other non-GET methods, arguments are sent as a JSON body, without the webhook message envelope. Configure endpoint credentials in toolHeaders, not in the prompt or parameter schema. These are credentials for your endpoint; do not forward your Orbitali API key.

The tool reference covers fixed parameters, optional runtime metadata, timeouts, and response limits. The runtime requires HTTPS and blocks private-network destinations.

3. Test the conversation

Activate the agent using the API activation step, or the dashboard. Test with a browser session or an assigned number. Ask about a mock order and inspect your endpoint request and call logs.

If the tool is not invoked, check its enabled state, description, and the agent instructions. If it fails, check endpoint authentication, the HTTP status, and the configured timeout. Test an unknown order as well as a successful lookup. Use mock data while developing actions that change records.

HTTP agents cannot fetch a dynamic prompt at startup. Use a webhook agent for that requirement.

On this page