Get started
An AI agent that looks things up
Create an AI voice agent with a tool your server answers, place a call it carries, answer its tool request and read what it extracted from the call.
In this quickstart you build an AI agent that confirms deliveries: it calls the customer, looks the order up on your server mid-call (a tool), and after the call hands you structured data it pulled from the conversation (an extraction). The full reference is AI voice agents.
Before you start
- A live key with
agents:read,agents:write,calls:write,contacts:write,transcripts:readandsettings:write. A test key creates test agents and test calls, which never reach a carrier and never run a tool — good for building the requests, not for hearing the agent. - Calling enabled and prepaid credit, as for any call (Place a call).
- An HTTPS endpoint of yours on a public host for the tool, answering within 4 seconds.
- A webhook endpoint subscribed to
call.summary.ready(withcalls:readandtranscripts:read) — see Receive webhooks.
Pick models this deployment runs
Every model in GET /v1/models says whether it is available here. Choose an available voice model: an agent naming one that is not is refused when you save it (422 MODEL_UNAVAILABLE, naming the provider), never when the call rings.
curl 'https://api.trovacast.com/v1/models' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Turn AI calls on
AI calls are switched off for a new organization. Read the settings for their version, then switch them on with it.
curl 'https://api.trovacast.com/v1/settings/calls' \
-H "Authorization: Bearer $TROVACAST_API_KEY"curl -X PATCH 'https://api.trovacast.com/v1/settings/calls' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"aiCallsEnabled": true,
"version": 1
}'Create the agent, with a tool and an extraction
curl -X POST 'https://api.trovacast.com/v1/agents' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: agent-delivery-confirmations' \
-H 'Content-Type: application/json' \
-d '{
"name": "Delivery confirmations",
"voice": {
"provider": "openai",
"model": "gpt-realtime"
},
"instructions": "You are Acme’s delivery assistant. Say you are an AI assistant and that the call may be recorded. Look the order up before you answer questions about it, confirm the delivery slot or offer another, then end the call politely.",
"firstMessage": "Hello, this is Acme’s delivery assistant. Is now a good time to talk about your order?",
"language": "en-IN",
"tools": [
{
"name": "lookup_order",
"description": "Finds an order by its number and answers its delivery slot and status.",
"parameters": {
"type": "object",
"properties": {
"orderId": {
"type": "string",
"description": "The order number"
}
},
"required": [
"orderId"
]
},
"url": "https://api.example.com/trovacast/tools/lookup-order"
}
],
"extraction": {
"schema": {
"type": "object",
"properties": {
"confirmed": {
"type": "boolean"
},
"newSlot": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"confirmed",
"newSlot"
]
}
}
}'The answer carries toolSigningSecret — once. Store it: it signs every tool request this agent sends. (POST /v1/agents/{agentId}/tool-secret replaces it if it leaks.)
Answer the tool
When the agent decides to look an order up, Trovacast POSTs { "event": "agent.tool_call", "tool": "lookup_order", "arguments": { "orderId": "1042" }, "callId", "agentId", "toolCallId", … } to the tool’s URL, signed with the tool-signing secret exactly like a webhook. Verify the signature on the raw body, then answer { "result": … } within 4 seconds — the agent speaks from it.
import express from "express";
import { verifyWebhookSignature } from "@trovacast/sdk";
const app = express();
app.post("/trovacast/tools/lookup-order", express.raw({ type: "application/json" }), async (req, res) => {
const signed = verifyWebhookSignature({
payload: req.body,
header: req.headers["trovacast-signature"],
secrets: [process.env.TROVACAST_TOOL_SECRET],
});
if (!signed) return res.sendStatus(400);
const { arguments: args } = JSON.parse(req.body.toString("utf8"));
const order = await orders.find(args.orderId); // your own lookup
res.json({
result: order
? { status: order.status, slot: order.deliverySlot }
: { error: "No order with that number" },
});
});import json, os
from flask import Flask, request, jsonify, abort
from trovacast import verify_webhook_signature
app = Flask(__name__)
@app.post("/trovacast/tools/lookup-order")
def lookup_order():
if not verify_webhook_signature(
request.get_data(),
request.headers.get("Trovacast-Signature"),
[os.environ["TROVACAST_TOOL_SECRET"]],
):
abort(400)
args = json.loads(request.get_data())["arguments"]
order = orders.find(args["orderId"]) # your own lookup
if order is None:
return jsonify(result={"error": "No order with that number"})
return jsonify(result={"status": order.status, "slot": order.delivery_slot})A slow, failing or oversized answer tells the agent the tool failed: it apologises and offers a follow-up, and never invents a result. Each tool call is on the call’s timeline by name and outcome — never its arguments or result.
Place the call
curl -X POST 'https://api.trovacast.com/v1/calls' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: ai-call-order-1042' \
-H 'Content-Type: application/json' \
-d '{
"mode": "AI_AGENT",
"to": {
"phone": "+919876543210"
},
"aiAgent": {
"agentId": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
"objective": "Confirm the delivery slot for order 1042."
},
"recording": {
"enabled": true,
"consentEvidence": {
"source": "VERBAL",
"text": "This call is recorded for quality and training.",
"capturedAt": "2026-11-06T09:30:00.000Z"
}
},
"maxDurationSec": 600
}'The call rings, the agent says its first message and the conversation runs on its own; the usual call events arrive as it does.
Read what it extracted
Once the call has ended and its transcript is final, the extraction runs with the summary. call.summary.ready brings it to your webhook; or read it yourself.
curl 'https://api.trovacast.com/v1/calls/2c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f/summary' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"object": "call_summary",
"callId": "2c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f",
"status": "ready",
"extraction": {
"status": "ready",
"data": {
"confirmed": false,
"newSlot": "2026-11-08T10:00:00.000Z"
},
"failureCode": null,
"extractedAt": "2026-11-06T10:00:00.000Z"
}
}extraction.data fits your schema (anything that does not is discarded, never stored), with any phone number in it masked to its last four digits. status: pending means it has not run yet; failed names why in failureCode.