Skip to content

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.

  1. 1DeclaretoolsList the tool on POST /v1/sessions
  2. 2Callagent.custom_tool_useThe agent asks, with params and an invocation_id
  3. 3Answeruser.tool_resultYour code replies with the same invocation_id
  4. 4ContinueThe agent reads your result and keeps working
Until you answer, the turn is suspended. It has not finished and it has not failed.

Each tool picks where its calls go with invocation. One session can mix both kinds.

Client toolWebhook tool
invocation"client""webhook"
The call arrivesOn your open event stream, as agent.custom_tool_useAs a signed POST to the session’s callback_url
You answer withuser.tool_result on POST …/eventsYour HTTP response
You keep upA live stream for the session’s lifeA public HTTPS endpoint
Best forA browser or app with a person in front of itServer-to-server work and slower 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.

Terminal window
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)

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:

Terminal window
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…"
} ] }'

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.

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.

Terminal window
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"]
}
} ]
}'

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.

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.

EventSent when
session.status_runningA turn starts
session.status_idleA turn ends. With requires_action, the session is waiting on you
agent.custom_tool_use, agent.gateThe agent asks for something
job.started, job.completed, job.failedA generation starts or finishes. job.completed carries outputs
session.errorA turn failed
session.status_terminatedThe 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.

FieldRule
name1 to 64 letters, digits, _ or -
descriptionUp to 1,024 characters
parametersA 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).

Each delivery, tool call or event, carries X-Luma-Signature, X-Luma-Timestamp and X-Luma-Delivery-Id.

  1. Compute HMAC-SHA256 over <X-Luma-Timestamp>.<raw body>, 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.

  • 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.
  • 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.
  • 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.