Skip to content

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.

Your code says which kind of request it is sending. The session doesn’t guess from the wording of a prompt.

RequestHow you send itWhat happens
A briefA 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 requestA 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 requestThe 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.

  1. 1Briefuser.messageYour user says what they want
  2. 2PlanThe agent decides the shots and models
  3. 3Generatejob.startedImages and video render
  4. 4CheckThe agent looks over each result before it counts
  5. 5ApprovependingYour user signs off, if you asked for it
  6. 6Deliverjob.completedFinished assets in the workspace
The agent reports every step on the session's event stream, so your product can show progress live.
What it isThink of it as
WorkspaceA storage location for assets. Sessions in it share files and defaults. A customer can have one or many.A project folder
SessionOne conversation with the agent, recorded in order.A chat thread
RunOne piece of work inside a session: a message, a generation or an app.A task
EventEverything sent and everything the agent does, numbered on one log.The thread’s history
ToolA way for the agent to call into your product, for an approval or a catalog lookup.A button the agent can press
  • 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.

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 sendOne generation requestA brief, a generation request, or a workflow-app run
Who decides the stepsYou choose the model and settingsYou can (generate run), or the agent plans them (brief)
ModelsLuma’s: uni-1, uni-1-max, Ray 3.2Luma’s plus third-party models your key is granted, narrowed per session
Output typesImage, video, layersImage, video, layers. A brief can also make audio when your key is granted audio models
Multi-step workNo: one request, one resultYes: the agent chains steps, and workflow apps run fixed pipelines
Where results liveA URL that expiresKept in a workspace by asset_id, reusable by later requests
MemoryNone: each call stands aloneThe session keeps its history, so later requests can refer to earlier results
Execution modeSubmit, poll, download. Parallel up to your concurrency limitOne event log per session. Generations can run alongside a brief, under the same concurrency limit
Getting resultsPoll the generationStream, page through the log, webhooks, or wait on the run
Your users in the loopNoApprovals, review steps, your own tools
CustomizationRequest fields onlyStanding instructions, reference files, skills, your own tools
CredentialsYour API key, from your server. An optional user_id labels the end userA short-lived token per end user. tenant_id keeps each customer’s work separate
BillingCredits per generationCredits per generation, plus the agent’s reasoning on briefs. Per-session caps
UIBuild your ownBuild your own on the event stream
  1. Quickstart: brief in, content out, in five calls.
  2. Sessions: how a conversation is recorded.
  3. Generate runs: send a generation straight to a model.