More capabilities
Layering, fonts, webhooks, model choice and platform tools.
Beyond its creative tools, the agent in a session can use a few more things Luma provides. Most are on by default. This page covers what they are and how to change them.
Platform tools
Section titled “Platform tools”Platform tools let the agent look at work, find assets and check results.
| Tool | What it lets the agent do | On by default |
|---|---|---|
read | Look at an image, several images as a contact sheet, or a video’s frames | Yes |
search_for_assets | Search every asset in the session’s workspace by name and meaning | Yes |
judge_tool | Check its own outputs against a question it states, and get scored rubrics back | Yes |
search_web | Search the web | No |
download_web_asset | Download an image or file from the web into the session | No |
Set platform_tools on session create to choose exactly which ones the session gets:
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"'", "platform_tools": { "type": "platform_toolset_v1", "configs": [ { "name": "read", "enabled": true }, { "name": "judge_tool", "enabled": true }, { "name": "search_web", "enabled": true } ] } }'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 = post( "/sessions", { "scope_id": workspace_id, "platform_tools": { "type": "platform_toolset_v1", "configs": [ {"name": "read", "enabled": True}, {"name": "judge_tool", "enabled": True}, {"name": "search_web", "enabled": True}, ], }, }, session_token,)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 = await post( "/sessions", { scope_id: workspaceId, platform_tools: { type: "platform_toolset_v1", configs: [ { name: "read", enabled: true }, { name: "judge_tool", enabled: true }, { name: "search_web", enabled: true }, ], }, }, sessionToken,);Once you send configs, the session gets only the tools you enable there.
judge_tool is limited to 20 calls per session. Leaving read out stops the agent looking at images and video, but it can still read skills.
Platform skills
Section titled “Platform skills”Platform skills are short pieces of Luma’s craft guidance. The agent reads them when the work calls for it, the same way it reads your skills.
| Skill | Guidance on |
|---|---|
platform-working-with-references | Working from reference images |
platform-visual-consistency | Keeping a look consistent across outputs |
platform-image-to-video-animation | Animating a still image |
platform-format-and-delivery | Sizes, aspect ratios and delivery formats |
platform-checking-results | Checking results before calling them done |
They’re on by default. Send "platform_skills": false on session create to turn them off.
Apps the agent can start
Section titled “Apps the agent can start”When your API key can run workflow apps, the agent in a session without an app also gets list_apps and start_app, so it can find an app and run it on your user’s behalf. A root session also gets answer_gate, which lets the agent answer an app’s question, but only after your user has sent a message since the question was shown.
An app the agent starts runs on the same stream and spends the same session’s credits. Its events carry the app run’s own run_id. If you show the conversation, filter agent.message by run_id, or the app’s messages look like the session’s agent said them.
To turn these tools off, add { "name": "app_tools", "enabled": false } to the configs of platform_tools. See Workflow apps to start an app yourself.
Sub-agents
Section titled “Sub-agents”The agents field on session create declares helper agents the main agent can hand work to. Each one you name gives the main agent a delegate_to_<name> tool. A delegated task runs as a child session, and the helper returns its result to the main agent when it’s done.
agents is a map from a name to a definition with a description, its own system_context and the tools it may use. Send {} to opt out of agents a workspace defines. agents can’t be sent beside app (422 APP.AGENT_OVERRIDE_FORBIDDEN). Email support+luma-agents-api@lumalabs.ai to use sub-agents.
Layering
Section titled “Layering”You can split an image into transparent layers inside a session, either with a generate run of type: "layering" or by asking the agent in a message. The layers land in the workspace and are billed to the session. See Generate runs.
/v1/fonts stores your brand’s font files beside your workspaces, so a layered image’s text layers can name your closest face and you can set their words as live type. Uploading a font doesn’t change what the image models draw. See Instructions and references.
Check what the session got
Section titled “Check what the session got”The create response and every GET /v1/sessions/{session_id} carry effective, the tools and skills the agent holds at its next turn:
{ "effective": { "platform_tools": ["read", "search_for_assets", "judge_tool"], "platform_skills": [ "platform-working-with-references", "platform-checking-results" ], "app_tools": ["list_apps", "start_app", "answer_gate"], "judge_calls_remaining": 20 }}If Luma switches one of these off for a running session, or back on, the next turn starts with a session.config_changed event carrying the new lists.
Details
Section titled “Details”Reserved tool names
Section titled “Reserved tool names”Your client and webhook tools share one namespace with Luma’s.
| Your tool’s name | What happens |
|---|---|
search_web, download_web_asset, read_skill and other reserved names | 422 SPEC.TOOL_NAME_COLLISION |
read, on a session that reads skills | 422 SPEC.TOOL_NAME_COLLISION. Send platform_skills: false and no skills to use your own read |
delegate_to_<name> or return_result, on a session with agents | 422 SPEC.TOOL_NAME_COLLISION |
read, search_for_assets or judge_tool, when that tool came only by default | Your tool keeps the name, and the session drops Luma’s |
list_apps or start_app | The session drops Luma’s list_apps and start_app |
answer_gate | The session drops Luma’s answer_gate |
Other rules
Section titled “Other rules”platform_toolsbesideappis refused with422 APP.PLATFORM_TOOL_OVERRIDE_FORBIDDEN. An app session gets all its tools from the app.platform_skillsmust be a JSONtrueorfalse.- Child sessions and app sessions don’t get platform skills or app tools.
- Past its limit,
judge_toolreturns a failedagent.tool_resultinstead of a judgment.
- Tools: add tools of your own.
- Generate runs: layering and direct generation.
- Instructions and references: fonts and brand inputs.