Skip to content
Going further

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 let the agent look at work, find assets and check results.

ToolWhat it lets the agent doOn by default
readLook at an image, several images as a contact sheet, or a video’s framesYes
search_for_assetsSearch every asset in the session’s workspace by name and meaningYes
judge_toolCheck its own outputs against a question it states, and get scored rubrics backYes
search_webSearch the webNo
download_web_assetDownload an image or file from the web into the sessionNo

Set platform_tools on session create to choose exactly which ones the session gets:

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"'",
"platform_tools": {
"type": "platform_toolset_v1",
"configs": [
{ "name": "read", "enabled": true },
{ "name": "judge_tool", "enabled": true },
{ "name": "search_web", "enabled": true }
]
}
}'

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

SkillGuidance on
platform-working-with-referencesWorking from reference images
platform-visual-consistencyKeeping a look consistent across outputs
platform-image-to-video-animationAnimating a still image
platform-format-and-deliverySizes, aspect ratios and delivery formats
platform-checking-resultsChecking results before calling them done

They’re on by default. Send "platform_skills": false on session create to turn them off.

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.

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.

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.

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.

Your client and webhook tools share one namespace with Luma’s.

Your tool’s nameWhat happens
search_web, download_web_asset, read_skill and other reserved names422 SPEC.TOOL_NAME_COLLISION
read, on a session that reads skills422 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 agents422 SPEC.TOOL_NAME_COLLISION
read, search_for_assets or judge_tool, when that tool came only by defaultYour tool keeps the name, and the session drops Luma’s
list_apps or start_appThe session drops Luma’s list_apps and start_app
answer_gateThe session drops Luma’s answer_gate
  • platform_tools beside app is refused with 422 APP.PLATFORM_TOOL_OVERRIDE_FORBIDDEN. An app session gets all its tools from the app.
  • platform_skills must be a JSON true or false.
  • Child sessions and app sessions don’t get platform skills or app tools.
  • Past its limit, judge_tool returns a failed agent.tool_result instead of a judgment.