--- title: Quickstart | Luma Agents description: Mint a session token, create a workspace and a session, send the agent a brief and watch it work, in five calls. --- This takes you from an API key to a finished image from the agent. Each step keeps the id the next one needs, so run the steps in order in one terminal or one script. You need an API key in `LUMA_AGENTS_API_KEY`; the cURL tab also needs `jq`. ## 1. Mint a session token Your API key stays on your server. Use it to mint a short-lived token for one of your end users, and use that token for every later call. - [cURL](#tab-panel-0-0) - [Python](#tab-panel-0-1) - [TypeScript](#tab-panel-0-2) ```bash SESSION_TOKEN=$(curl -s -X POST https://agents.lumalabs.ai/v1/auth/token \ -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "user_id": "user-8812", "tenant_id": "customer-4417" }' \ | jq -r .session_token) ``` ```python import json import os import 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_token = post( "/auth/token", {"user_id": "user-8812", "tenant_id": "customer-4417"}, os.environ["LUMA_AGENTS_API_KEY"], )["session_token"] ``` ```typescript const BASE = "https://agents.lumalabs.ai/v1"; async function post( path: string, body: unknown, token: string, headers: Record = {}, ) { 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_token: sessionToken } = await post( "/auth/token", { user_id: "user-8812", tenant_id: "customer-4417" }, process.env.LUMA_AGENTS_API_KEY!, ); ``` `user_id` is your id for the person. `tenant_id` is your id for their company, and it hides one customer’s work from every other customer. ## 2. Create a workspace - [cURL](#tab-panel-1-0) - [Python](#tab-panel-1-1) - [TypeScript](#tab-panel-1-2) ```bash WORKSPACE_ID=$(curl -s -X POST https://agents.lumalabs.ai/v1/scopes \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "key": "brand-workspace", "display_name": "Example Bakery" }' \ | jq -r .scope_id) ``` ```python workspace_id = post( "/scopes", { "key": "brand-workspace", "display_name": "Example Bakery", }, session_token, )["scope_id"] ``` ```typescript const { scope_id: workspaceId } = await post( "/scopes", { key: "brand-workspace", display_name: "Example Bakery", }, sessionToken, ); ``` A workspace holds the assets your sessions make and use. Posting the same `key` again returns the same workspace. ## 3. Open a session - [cURL](#tab-panel-2-0) - [Python](#tab-panel-2-1) - [TypeScript](#tab-panel-2-2) ```bash SESSION_ID=$(curl -s -X POST https://agents.lumalabs.ai/v1/sessions \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: quickstart-1" \ -d '{ "scope_id": "'"$WORKSPACE_ID"'", "system_context": "You are the creative department for a small bakery.", "expires_in_seconds": 3600, "cost_policy": { "max_total_credits": 2000 } }' \ | jq -r .session_id) ``` ```python session_id = post( "/sessions", { "scope_id": workspace_id, "system_context": "You are the creative department for a small bakery.", "expires_in_seconds": 3600, "cost_policy": {"max_total_credits": 2000}, }, session_token, headers={"Idempotency-Key": "quickstart-1"}, )["session_id"] ``` ```typescript const { session_id: sessionId } = await post( "/sessions", { scope_id: workspaceId, system_context: "You are the creative department for a small bakery.", expires_in_seconds: 3600, cost_policy: { max_total_credits: 2000 }, }, sessionToken, { "Idempotency-Key": "quickstart-1" }, ); ``` `system_context` is standing instructions the agent follows on every turn. `max_total_credits` caps what this session can spend. ## 4. Send a brief - [cURL](#tab-panel-3-0) - [Python](#tab-panel-3-1) - [TypeScript](#tab-panel-3-2) ```bash curl -s -X POST https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/events \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "events": [ { "type": "user.message", "content": "Make a square image of our sourdough loaf on a rustic table, morning light.", "idempotency_key": "'"$SESSION_ID"'-msg-1" } ] }' ``` ```python ack = post( f"/sessions/{session_id}/events", {"events": [{ "type": "user.message", "content": "Make a square image of our sourdough loaf on a rustic table, morning light.", "idempotency_key": f"{session_id}-msg-1", }]}, session_token, ) print(ack["data"][0]["status"]) # "accepted" ``` ```typescript const ack = await post( `/sessions/${sessionId}/events`, { events: [ { type: "user.message", content: "Make a square image of our sourdough loaf on a rustic table, morning light.", idempotency_key: `${sessionId}-msg-1`, }, ], }, sessionToken, ); console.log(ack.data[0].status); // "accepted" ``` The response has one entry per event you sent. `"status": "accepted"` in `data[0]` means the brief was recorded and the agent’s turn was scheduled; the work itself appears on the stream. ```json { "data": [ { "type": "user.message", "status": "accepted", "id": "sevt_emsbs", "seq": 1, "result": { "run_id": "e2089f1e-5333-4eb1-985e-6ca88f3adb04", "message_seq": 0 } } ] } ``` ## 5. Watch the agent work - [cURL](#tab-panel-4-0) - [Python](#tab-panel-4-1) - [TypeScript](#tab-panel-4-2) ```bash curl -s -N "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/events/stream?after_seq=0" \ -H "Authorization: Bearer $SESSION_TOKEN" ``` ```python request = urllib.request.Request( f"{BASE}/sessions/{session_id}/events/stream?after_seq=0", headers={"Authorization": f"Bearer {session_token}"}, ) with urllib.request.urlopen(request) as stream: for raw in stream: line = raw.decode().strip() if not line.startswith("data:"): continue event = json.loads(line[5:]) print(event.get("seq"), event.get("type")) if event.get("type") == "job.completed": print("image:", event["outputs"][0]["url"]) if event.get("type") == "session.status_idle": break ``` ```typescript const stream = await fetch( `${BASE}/sessions/${sessionId}/events/stream?after_seq=0`, { headers: { Authorization: `Bearer ${sessionToken}` }, }, ); const reader = stream.body!.pipeThrough(new TextDecoderStream()).getReader(); let buffer = ""; read: while (true) { const { value, done } = await reader.read(); if (done) break; buffer += value; const lines = buffer.split("\n"); buffer = lines.pop()!; for (const line of lines) { if (!line.startsWith("data:")) continue; const event = JSON.parse(line.slice(5)); console.log(event.seq, event.type); if (event.type === "job.completed") console.log("image:", event.outputs[0].url); if (event.type === "session.status_idle") break read; } } await reader.cancel(); ``` `after_seq=0` replays the log from the start and then stays open, so it doesn’t matter that you sent the brief first. This is the log the brief above produced on production: 1. 1**Your brief**`user.message`seq 1. Your input comes back first, so the log holds everything 2. 2**Agent starts**`session.status_running, run.started`The agent picks up the brief as a run of kind brief 3. 3**Plan and tools**`agent.message, agent.tool_use, agent.tool_result`It says what it will do, searches the workspace for references, and picks a model 4. 4**Generation**`job.started → job.completed`A second session.status\_running marks the agent resuming when the image is ready. job.completed carries outputs\[].url and asset\_id 5. 5**Reply**`agent.message`The agent describes the finished image 6. 6**Wrap-up**`run.completed, session.usage`The run closes and reports credits\_charged 7. 7**Done**`session.status_idle`stop\_reason end\_turn: the agent is waiting for your next message The agent decides which tools to call, so the middle of the log varies from brief to brief, and it may ask a question instead of generating. agent.message\_delta frames stream the reply text while you are connected; they have no seq and are not replayed. The `job.completed` event carries the result: ```json { "type": "job.completed", "seq": 14, "job_id": "apijob_a95785b972bb4296", "outputs": [ { "type": "image", "url": "https://…", "asset_id": "XadkmWNE", "mime": "image/png", "width": 2048, "height": 2048 } ], "credits_charged": 35 } ``` The URL is presigned and expires; keep the `asset_id` to refer to the image later. ## What just happened You created a workspace for one customer, opened a session capped at 2,000 credits, and sent a brief. The agent searched the workspace, chose a model, generated the image and reported every step on one numbered log. This run charged 35 credits. ## Next - [Streaming](/agents/streaming/index.md): reconnect without missing anything. - [Approvals and review](/agents/approvals/index.md): let your user sign off before anything ships. - [Workflow apps](/agents/workflow-apps/index.md): run a ready-made workflow instead of a free-form brief.