What is an agent session?
Run Luma's creative agent inside your product. Open a session, send it a request, and stream back everything it plans, calls and renders.
An agent session puts Luma’s creative agent inside your product. Your product sends it one of three kinds of request: a brief for the agent to work through, a generation request that goes straight to a model, or an app invocation request that runs one of Luma’s workflow apps.
Brief in. Content out. You build the experience. Luma powers the creative.
Three kinds of request
Section titled “Three kinds of request”Your code says which kind of request it is sending. The session doesn’t guess from the wording of a prompt.
| Request | How you send it | What happens |
|---|---|---|
| A brief | A user.message event with free text, such as “Find reference photos of ragdoll cats, then make a set of images of them.” | The agent researches, plans, picks the models, generates and checks the results. |
| A generation request | A run with kind: "generate", naming the model and its options. | Goes straight to the model provider, with no agent planning in between. |
| An app invocation request | The app’s slug on the session, or a run with kind: "capability", plus the app’s form fields. | Runs one of the workflow apps Luma has built and tested for customers. |
All three share the session’s workspace, event stream and budget, so you can mix them: generate a hero image directly, then ask the agent to build a campaign around it.
How the agent works through a brief
Section titled “How the agent works through a brief”- 1Brief
user.messageYour user says what they want - 2PlanThe agent decides the shots and models
- 3Generate
job.startedImages and video render - 4CheckThe agent looks over each result before it counts
- 5Approve
pendingYour user signs off, if you asked for it - 6Deliver
job.completedFinished assets in the workspace
Five things to know
Section titled “Five things to know”| What it is | Think of it as | |
|---|---|---|
| Workspace | A storage location for assets. Sessions in it share files and defaults. A customer can have one or many. | A project folder |
| Session | One conversation with the agent, recorded in order. | A chat thread |
| Run | One piece of work inside a session: a message, a generation or an app. | A task |
| Event | Everything sent and everything the agent does, numbered on one log. | The thread’s history |
| Tool | A way for the agent to call into your product, for an approval or a catalog lookup. | A button the agent can press |
What the agent does for you
Section titled “What the agent does for you”- It picks the model. The agent chooses between Luma and third-party image and video models for each step.
- It stays inside your budget. Set a credit cap per session. When the cap is reached, the agent stops cleanly and keeps what it made.
- It pauses only where a review is set up. A run stops for sign-off at a client tool you register or at an app’s review step. See Approvals and review.
- It uses what you give it. Standing instructions and reference files are optional inputs.
Agents API and the Luma API
Section titled “Agents API and the Luma API”The Luma API (/v1/generations) runs one generation per request. The Agents API adds a session around your requests: memory, a workspace for results, the agent’s planning and your users in the loop.
Luma API (/v1/generations) | Agents API (sessions) | |
|---|---|---|
| What you send | One generation request | A brief, a generation request, or a workflow-app run |
| Who decides the steps | You choose the model and settings | You can (generate run), or the agent plans them (brief) |
| Models | Luma’s: uni-1, uni-1-max, Ray 3.2 | Luma’s plus third-party models your key is granted, narrowed per session |
| Output types | Image, video, layers | Image, video, layers. A brief can also make audio when your key is granted audio models |
| Multi-step work | No: one request, one result | Yes: the agent chains steps, and workflow apps run fixed pipelines |
| Where results live | A URL that expires | Kept in a workspace by asset_id, reusable by later requests |
| Memory | None: each call stands alone | The session keeps its history, so later requests can refer to earlier results |
| Execution mode | Submit, poll, download. Parallel up to your concurrency limit | One event log per session. Generations can run alongside a brief, under the same concurrency limit |
| Getting results | Poll the generation | Stream, page through the log, webhooks, or wait on the run |
| Your users in the loop | No | Approvals, review steps, your own tools |
| Customization | Request fields only | Standing instructions, reference files, skills, your own tools |
| Credentials | Your API key, from your server. An optional user_id labels the end user | A short-lived token per end user. tenant_id keeps each customer’s work separate |
| Billing | Credits per generation | Credits per generation, plus the agent’s reasoning on briefs. Per-session caps |
| UI | Build your own | Build your own on the event stream |
- Quickstart: brief in, content out, in five calls.
- Sessions: how a conversation is recorded.
- Generate runs: send a generation straight to a model.