Tools: let the agent call your code
Let the agent call your own code. Declare a tool on the session, answer each call, and keep the turn moving.
Some of what the agent needs lives only in your systems: a product catalog, a stock count, your user’s sign-off. A tool lets the agent ask your code for it. You declare the tool when you create the session. When the agent calls it, the turn pauses until your answer arrives, then the agent carries on with what you sent.
- 1Declare
toolsList the tool on POST /v1/sessions - 2Call
agent.custom_tool_useThe agent asks, with params and an invocation_id - 3Answer
user.tool_resultYour code replies with the same invocation_id - 4ContinueThe agent reads your result and keeps working
Two ways to answer
Section titled “Two ways to answer”Each tool picks where its calls go with invocation. One session can mix both kinds.
| Client tool | Webhook tool | |
|---|---|---|
invocation | "client" | "webhook" |
| The call arrives | On your open event stream, as agent.custom_tool_use | As a signed POST to the session’s callback_url |
| You answer with | user.tool_result on POST …/events | Your HTTP response |
| You keep up | A live stream for the session’s life | A public HTTPS endpoint |
| Best for | A browser or app with a person in front of it | Server-to-server work and slower answers |
Client tools: your front end answers
Section titled “Client tools: your front end answers”Declare the tool in tools on session create. The description is how the agent decides when to call it, so say what it returns and when to use it.
SESSION_ID=$(curl -s -X POST https://agents.lumalabs.ai/v1/sessions \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: tools-1" \ -d '{ "scope_id": "'"$WORKSPACE_ID"'", "tools": [ { "name": "lookup_products", "description": "Search the bakery product catalog by free-text query.", "invocation": "client", "parameters": { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] } } ] }' | jq -r .session_id)import jsonimport urllib.request
BASE = "https://agents.lumalabs.ai/v1"
def post(path, body, token, headers=None): request = urllib.request.Request( BASE + path, method="POST", data=json.dumps(body).encode(), headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json", **(headers or {})}, ) with urllib.request.urlopen(request) as response: return json.load(response)
session_id = post( "/sessions", { "scope_id": workspace_id, "tools": [{ "name": "lookup_products", "description": "Search the bakery product catalog by free-text query.", "invocation": "client", "parameters": { "type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"], }, }], }, session_token, headers={"Idempotency-Key": "tools-1"},)["session_id"]const BASE = "https://agents.lumalabs.ai/v1";
async function post( path: string, body: unknown, token: string, headers: Record<string, string> = {},) { const response = await fetch(BASE + path, { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...headers, }, body: JSON.stringify(body), }); if (!response.ok) throw new Error(`${response.status} ${await response.text()}`); return response.json();}
const { session_id: sessionId } = await post( "/sessions", { scope_id: workspaceId, tools: [ { name: "lookup_products", description: "Search the bakery product catalog by free-text query.", invocation: "client", parameters: { type: "object", properties: { query: { type: "string" } }, required: ["query"], }, }, ], }, sessionToken, { "Idempotency-Key": "tools-1" },);When the agent calls it, your stream carries:
{ "type": "agent.custom_tool_use", "tool": "lookup_products", "params": { "query": "sourdough" }, "invocation_id": "toolu_01K7…"}Run your code and send the result back with the same invocation_id:
curl -s -X POST https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/events \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "events": [ { "type": "user.tool_result", "invocation_id": "toolu_01K7…", "result": { "products": [ { "sku": "SD-01", "name": "Sourdough loaf" } ] }, "idempotency_key": "tool-toolu_01K7…" } ] }'invocation_id = "toolu_01K7…"ack = post( f"/sessions/{session_id}/events", {"events": [{ "type": "user.tool_result", "invocation_id": invocation_id, "result": {"products": [{"sku": "SD-01", "name": "Sourdough loaf"}]}, "idempotency_key": f"tool-{invocation_id}", }]}, session_token,)print(ack["data"][0]["status"])const invocationId = "toolu_01K7…";const ack = await post( `/sessions/${sessionId}/events`, { events: [ { type: "user.tool_result", invocation_id: invocationId, result: { products: [{ sku: "SD-01", name: "Sourdough loaf" }] }, idempotency_key: `tool-${invocationId}`, }, ], }, sessionToken,);console.log(ack.data[0].status);Answer every call, including ones you cannot handle. Return { "error": "…" } and the agent can recover. A call you never answer holds the session until the call’s deadline or the end of the session. Keying the answer on tool-<invocation_id> makes a resend safe. A result containing attachment_id shows the agent that image.
A client tool is also how you build a sign-off step. The agent only pauses for approval when you set one up. See Approvals and review.
Webhook tools: your server answers
Section titled “Webhook tools: your server answers”A webhook tool needs a callback_url on the session. Luma POSTs each call there and reads the answer from your response, so nothing has to hold a stream open.
curl -s -X POST https://agents.lumalabs.ai/v1/sessions \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "scope_id": "'"$WORKSPACE_ID"'", "callback_url": "https://api.example.com/luma/webhooks", "tools": [ { "name": "lookup_inventory", "description": "Return the current stock count for a product SKU.", "invocation": "webhook", "parameters": { "type": "object", "properties": { "sku": { "type": "string" } }, "required": ["sku"] } } ] }'created = post( "/sessions", { "scope_id": workspace_id, "callback_url": "https://api.example.com/luma/webhooks", "tools": [{ "name": "lookup_inventory", "description": "Return the current stock count for a product SKU.", "invocation": "webhook", "parameters": { "type": "object", "properties": {"sku": {"type": "string"}}, "required": ["sku"], }, }], }, session_token,)webhook_secret = created["webhook_secret"]const created = await post( "/sessions", { scope_id: workspaceId, callback_url: "https://api.example.com/luma/webhooks", tools: [ { name: "lookup_inventory", description: "Return the current stock count for a product SKU.", invocation: "webhook", parameters: { type: "object", properties: { sku: { type: "string" } }, required: ["sku"], }, }, ], }, sessionToken,);const webhookSecret: string = created.webhook_secret;The response carries webhook_secret once. Store it with the session id: you need it to verify every request. Your endpoint receives the call in data:
{ "event": "agent.custom_tool_use", "session_id": "91091cf2-…", "data": { "tool": "lookup_inventory", "params": { "sku": "SD-01" }, "invocation_id": "toolu_016r…" }}Verify the signature, then answer with any 2xx and a JSON body:
{ "result": { "sku": "SD-01", "in_stock": 42 } }Answer within 30 seconds. For anything slower, such as a queue hop or a person’s approval, return 202 Accepted and send a user.tool_result later, exactly as a client tool does. The call may stay open for 15 minutes in total.
Webhooks: hear about results
Section titled “Webhooks: hear about results”The same callback_url also receives the session events a backend acts on, so you don’t need to hold a stream open to learn that work finished. Every delivery is signed with the same secret.
| Event | Sent when |
|---|---|
session.status_running | A turn starts |
session.status_idle | A turn ends. With requires_action, the session is waiting on you |
agent.custom_tool_use, agent.gate | The agent asks for something |
job.started, job.completed, job.failed | A generation starts or finishes. job.completed carries outputs |
session.error | A turn failed |
session.status_terminated | The session ended |
Text deltas, your own inputs and tool activity stay on the stream. Answer 2xx to any event you don’t handle.
Webhooks are a fast path, not the record. Deliveries are retried but can still be lost, so keep a cursor and backfill from GET /v1/sessions/{session_id}/events?after_seq=<cursor> when your receiver restarts or a session goes quiet.
Details
Section titled “Details”Tool rules
Section titled “Tool rules”| Field | Rule |
|---|---|
name | 1 to 64 letters, digits, _ or - |
description | Up to 1,024 characters |
parameters | A JSON Schema with "type": "object" at the top, up to 8 KB |
A session takes up to 64 tools. A bad name or schema is refused at create with 422 SPEC.TOOL_INVALID, and a duplicate or reserved name with 422 SPEC.TOOL_NAME_COLLISION (see Reserved tool names).
Verify a signature
Section titled “Verify a signature”Each delivery, tool call or event, carries X-Luma-Signature, X-Luma-Timestamp and X-Luma-Delivery-Id.
- Compute HMAC-SHA256 over
<X-Luma-Timestamp>.<raw body>, keyed with the wholewebhook_secretincluding itswhsec_prefix. - Compare the hex digest with the part of
X-Luma-Signatureaftersha256=, in constant time. - Reject a timestamp more than five minutes from now.
Verify the raw bytes before you parse them, and de-duplicate on X-Luma-Delivery-Id.
Retries and timeouts
Section titled “Retries and timeouts”- An event delivery should get a
2xxwithin 10 seconds. A timeout,408,429or5xxis retried five times over about 36 minutes. Other4xxare not retried. Events can arrive out of order, so order byX-Luma-Event-Seq. - A webhook tool call is retried once, on a
5xxor429only. A non-2xx, a non-JSON body or a body over 64 KB settles the call as a tool error, and the turn carries on. - At the 15-minute deadline an unanswered call is settled as an error, recorded as a
user.tool_resultwith a code such asTOOL.DEADLINE_EXCEEDED.
Edge cases
Section titled “Edge cases”- Your endpoint also gets a notice for each client tool call. It has an
X-Luma-Event-Seqheader; a webhook tool call does not. Don’t answer notices from your backend, or it races your stream consumer. - A webhook tool call is not announced on the stream. While your backend holds it, the session reads
runningandGET /v1/sessions/{session_id}lists it underpending_tool_invocations. - An answer to a call that is no longer waiting is rejected with
TOOL_RESPONSE.UNKNOWN_INVOCATION.
- Approvals and review: pause for your user’s sign-off.
- Skills: give the agent standing guidance on how to use your tools.
- Reference: every route and the errors you will meet.