Tools

Mid-call, the agent decides when to invoke a tool based on what the caller said and what your tool's description says it does. For a custom tool, Aethex makes a server-to-server HTTPS call to your endpoint and feeds the response back into the conversation:

The whole loop runs inside the call, with the caller waiting on the line. Keep your endpoint fast: sub-second response is ideal. The agent always gets an answer within 9 seconds, and that limit covers the DNS lookup, the connection and the whole response.

Every agent gets these two automatically. They are enabled by configuration on the agent (end_call_enabled, transfer_phone_number), not by registering anything.

Register your own tool with one POST. The pipeline picks it up on the next call against that agent.

Fields

Register a tool

import os, requests

API_KEY = os.environ["AETHEX_API_KEY"]
BASE_URL = "https://api.aethexai.com/api/v1"
AGENT_ID = "ag_..."

resp = requests.post(
    f"{BASE_URL}/agents/{AGENT_ID}/tools",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "name": "lookup_order",
        "description": (
            "Look up the status of a customer order by order ID. "
            "Use when the caller asks about an order or shipment they have placed."
        ),
        "parameters_schema": {
            "type": "object",
            "properties": {
                "order_id": {
                    "type": "string",
                    "description": "The order ID, alphanumeric. Example: A1B2C3.",
                },
            },
            "required": ["order_id"],
        },
        "endpoint_url": "https://orders.example.com/aethex/lookup",
        "headers": {"Authorization": "Bearer your-shared-secret"},
    },
)
resp.raise_for_status()
print(resp.json())

When the LLM invokes a custom tool, Aethex dispatches to your endpoint_url using the tool's http_method (POST by default). You have 9 seconds to respond, counting the DNS lookup, the connection and the whole response.

POST request (default)

{
  "arguments": {
    "order_id": "A1B2C3"
  },
  "agent_id": "ag_...",
  "conversation_id": "co_...",
  "call_id": "ca_..."
}

GET request

For http_method: GET, LLM arguments are appended to the URL as query parameters and the contextual IDs are forwarded as headers. No body is sent. Note: arguments land in your web server's access logs.

GET /aethex/lookup?order_id=A1B2C3&in_stock=true&tags=%5B%22prime%22%5D
Host: orders.example.com
X-Aethex-Agent-Id: ag_...
X-Aethex-Conversation-Id: co_...
X-Aethex-Call-Id: ca_...
(no body)

Response

Return a JSON body with whatever the agent should know. Aethex feeds the entire response into the LLM as the tool result, so structure it so the LLM can read it (key/value pairs, plain English fields).

{
  "status": "shipped",
  "tracking_number": "1Z999AA10123456784",
  "estimated_delivery": "Tomorrow, 3 PM"
}

Errors

Any 4xx, 5xx, timeout, or network failure is captured as a tool error and surfaced to the LLM as a JSON object like {"error": "<reason>"}. The agent then handles it gracefully (acknowledges the failure, offers to transfer). The call is never killed because your endpoint is down. If a tool fails, it still answers the agent, so the call never stalls waiting on it.

Once your agent has tools, give it grounded knowledge: see Knowledge base for uploading reference documents the agent can pull from at call time.