Agent Recipes

What Agents Should Prefer

For interactive agents, prefer hosted MCP:

https://app.uselamina.ai/mcp/agent

For server-side agents, use the SDK or REST API with LAMINA_API_KEY. Hosted MCP and REST share the same runtime model: create work, preserve runId, wait or subscribe to completion, inspect typed outputs, and reuse final artifacts explicitly.

Recipe 1: Hosted MCP Creative Run

After installing Lamina MCP in Claude Code, Codex, Cursor, or another MCP client, use this flow:

Create

Call lamina_create with brief, platform, and modality.

Clarify if needed

If the response status is needs_input, ask the user for the listed missing fields and call lamina_create again with those values in inputs.

Wait

Call lamina_status with runId and wait=true.

Reuse

Inspect each output’s type, status, and value. Reuse completed asset URLs as explicit references in the next Lamina run.

Example MCP call:

{
  "tool": "lamina_create",
  "arguments": {
    "brief": "Create a cinematic launch image for a premium running shoe.",
    "platform": "instagram",
    "modality": "image"
  }
}

Expected started response:

{
  "runId": "99ebc7c6-24f3-4fc2-9d53-2e3f49f3bec1",
  "status": "queued",
  "workflowName": "Product Hero Image",
  "selectedApp": {
    "name": "Product Hero Image",
    "whyMatched": "Matches image launch creative intent"
  }
}

Expected clarification response:

{
  "runId": null,
  "status": "needs_input",
  "needsInput": {
    "message": "This workflow needs additional inputs before Lamina can start the run.",
    "missing": [
      {
        "name": "Product Image",
        "type": "url",
        "accept": ["image"]
      }
    ],
    "suggestedPrompt": "Ask the user for Product Image."
  }
}

Recipe 2: TypeScript Agent With SDK

Use this for Node.js agents, backend workers, and agent runtimes that own their own API key.

import { LaminaClient } from '@uselamina/sdk';

const client = LaminaClient.fromEnv();

const created = await client.content.create({
  brief: 'Create a premium Instagram launch visual for a running shoe.',
  platform: 'instagram',
  modality: 'image',
});

if (created.data.needsInput || !created.data.runId) {
  console.log(created.data.needsInput?.missing);
  console.log(created.data.needsInput?.suggestedPrompt);
  process.exit(0);
}

const result = await client.runs.wait(created.data.runId, {
  timeoutMs: 120_000,
  intervalMs: 4_000,
});

for (const output of result.data.outputs) {
  if (output.status === 'completed') {
    console.log(output.type, output.value);
  }
}

Full example:

examples/agents/typescript/creative-agent-recipe.ts

Recipe 3: Python Agent With REST

Use this when the agent is written in Python or runs in an environment without the TypeScript SDK.

created = request(
    "/v1/content/create",
    method="POST",
    body={
        "brief": "Create a cinematic launch image for a premium running shoe.",
        "platform": "instagram",
        "modality": "image",
    },
)

if created["data"].get("needsInput") or not created["data"].get("runId"):
    print(created["data"].get("needsInput", {}).get("missing", []))
    raise SystemExit(0)

status = wait_for_run(created["data"]["runId"])

Full example:

examples/agents/python/creative_agent_recipe.py

Recipe 4: Brand-Aware Planning

Agents should call brand context before generating when the user asks for brand-safe, campaign-safe, or performance-aware content.

const brand = await client.intelligence.getBrandContext({
  platform: 'instagram',
  modality: 'image',
  objective: 'launch campaign',
});

console.log(brand.data.brandDna?.guardrails ?? []);
console.log(brand.data.guidance?.promptDirectives ?? []);

For MCP clients, use lamina_brand before lamina_create when the agent needs explicit voice, visual, guardrail, or winning-pattern context.

Recipe 5: Artifact Reuse

Agents should not scrape provider-specific payloads. Treat completed outputs with string value fields as reusable artifact URLs.

const artifacts = result.data.outputs
  .filter((output) => output.status === 'completed' && typeof output.value === 'string')
  .map((output) => ({ type: output.type, url: output.value }));

if (artifacts[0]) {
  await client.content.create({
    brief: 'Create a matching story variant using this reference.',
    platform: 'instagram-story',
    modality: artifacts[0].type,
    inputs: {
      Reference: artifacts[0].url,
    },
  });
}

Smoke Test Checklist

Run this checklist for every supported MCP client before broad distribution:

Install https://app.uselamina.ai/mcp/agent.
Complete OAuth and choose a workspace.
Confirm the client lists the Lamina tools.
Call lamina_discover for an image or video launch brief.
Call lamina_create with a simple brief.
If needs_input is returned, provide the missing input and retry.
Call lamina_status with wait=true.
Confirm completed outputs include typed values the agent can reuse.
Remove or revoke the client after testing if it used a temporary workspace.

Troubleshooting

authorization_required: start OAuth from the MCP client or reinstall the hosted server.
insufficient_scope: reconnect and approve the requested scope.
needs_input: ask the user for the listed missing field; do not start a run with guessed data.
failed: surface errorMessage and output-level errors; do not blindly retry invalid inputs.
Timeout while waiting: call lamina_status again with the same runId.

Overview

Install

Concepts

API Reference

Guides

What Agents Should Prefer

Recipe 1: Hosted MCP Creative Run

Recipe 2: TypeScript Agent With SDK

Recipe 3: Python Agent With REST

Recipe 4: Brand-Aware Planning

Recipe 5: Artifact Reuse

Smoke Test Checklist

Troubleshooting

​What Agents Should Prefer

​Recipe 1: Hosted MCP Creative Run

​Recipe 2: TypeScript Agent With SDK

​Recipe 3: Python Agent With REST

​Recipe 4: Brand-Aware Planning

​Recipe 5: Artifact Reuse

​Smoke Test Checklist

​Troubleshooting

What Agents Should Prefer

Recipe 1: Hosted MCP Creative Run

Recipe 2: TypeScript Agent With SDK

Recipe 3: Python Agent With REST

Recipe 4: Brand-Aware Planning

Recipe 5: Artifact Reuse

Smoke Test Checklist

Troubleshooting