--- title: What is an agent session? | Luma Agents description: 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 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](/agents/generations/index.md)** | 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](/agents/workflow-apps/index.md)** | 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 1. 1**Brief**`user.message`Your user says what they want 2. 2**Plan**The agent decides the shots and models 3. 3**Generate**`job.started`Images and video render 4. 4**Check**The agent looks over each result before it counts 5. 5**Approve**`pending`Your user signs off, if you asked for it 6. 6**Deliver**`job.completed`Finished assets in the workspace The agent reports every step on the session's event stream, so your product can show progress live. ## 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 - **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](/agents/approvals/index.md). - **It uses what you give it.** [Standing instructions and reference files](/agents/instructions/index.md) are optional inputs. ## Agents API and the Luma API The [Luma API](/guides/index.md) (`/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](/agents/generations/index.md)), 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](/agents/workflow-apps/index.md) run fixed pipelines | | **Where results live** | A URL that expires | Kept in a [workspace](/agents/workspaces/index.md) 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](/agents/approvals/index.md), review steps, [your own tools](/agents/tools/index.md) | | **Customization** | Request fields only | Standing instructions, reference files, [skills](/agents/skills/index.md), 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](/agents/streaming/index.md) | ## Next 1. [Quickstart](/agents/quickstart/index.md): brief in, content out, in five calls. 2. [Sessions](/agents/sessions/index.md): how a conversation is recorded. 3. [Generate runs](/agents/generations/index.md): send a generation straight to a model.