--- title: 'Tools: let the agent call your code | Luma Agents' description: 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. 1. 1**Declare**`tools`List the tool on POST /v1/sessions 2. 2**Call**`agent.custom_tool_use`The agent asks, with params and an invocation\_id 3. 3**Answer**`user.tool_result`Your code replies with the same invocation\_id 4. 4**Continue**The agent reads your result and keeps working Until you answer, the turn is suspended. It has not finished and it has not failed. ## 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 | `invocation` defaults to `webhook`. Send it on every tool. A tool you meant for your stream that is declared without it never reaches the stream, and with no `callback_url` the agent is told the tool cannot run. The session then finishes having done less than you asked. ## 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. - [cURL](#tab-panel-0-0) - [Python](#tab-panel-0-1) - [TypeScript](#tab-panel-0-2) ```bash 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) ``` ```python import json import 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"] ``` ```typescript const BASE = "https://agents.lumalabs.ai/v1"; async function post( path: string, body: unknown, token: string, headers: Record = {}, ) { 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: ```json { "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](#tab-panel-1-0) - [Python](#tab-panel-1-1) - [TypeScript](#tab-panel-1-2) ```bash 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…" } ] }' ``` ```python 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"]) ``` ```typescript 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-` 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](/agents/approvals/index.md). ## 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](#tab-panel-2-0) - [Python](#tab-panel-2-1) - [TypeScript](#tab-panel-2-2) ```bash 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"] } } ] }' ``` ```python 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"] ``` ```typescript 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`: ```json { "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: ```json { "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 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=` when your receiver restarts or a session goes quiet. ## Details ### 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](/agents/more/index.md)). ### Verify a signature Each delivery, tool call or event, carries `X-Luma-Signature`, `X-Luma-Timestamp` and `X-Luma-Delivery-Id`. 1. Compute HMAC-SHA256 over `.`, keyed with the whole `webhook_secret` including its `whsec_` prefix. 2. Compare the hex digest with the part of `X-Luma-Signature` after `sha256=`, in constant time. 3. 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 - An event delivery should get a `2xx` within 10 seconds. A timeout, `408`, `429` or `5xx` is retried five times over about 36 minutes. Other `4xx` are not retried. Events can arrive out of order, so order by `X-Luma-Event-Seq`. - A webhook tool call is retried once, on a `5xx` or `429` only. 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_result` with a code such as `TOOL.DEADLINE_EXCEEDED`. ### Edge cases - Your endpoint also gets a notice for each client tool call. It has an `X-Luma-Event-Seq` header; 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 `running` and `GET /v1/sessions/{session_id}` lists it under `pending_tool_invocations`. - An answer to a call that is no longer waiting is rejected with `TOOL_RESPONSE.UNKNOWN_INVOCATION`. ## Next - [Approvals and review](/agents/approvals/index.md): pause for your user’s sign-off. - [Skills](/agents/skills/index.md): give the agent standing guidance on how to use your tools. - [Reference](/agents/reference/index.md): every route and the errors you will meet.