Agents

Run tasks and workflows with an agent

Discover compact MCP resources, load one detailed contract, estimate paid work, start it deliberately, and follow its lifecycle.

On this page

Use list tools for compact discovery, then fetch one task, workflow, starter, generation, or run when you need its full contract. This keeps agent context focused and avoids acting on stale summaries.

A generation task creates or processes media directly. A workflow starter exposes a curated input and output contract. A Console workflow is an organization-owned reusable graph and must be read before edits or runs so the current definition_hash can guard the action.

Discover compact resources first

List compactly

Discover tasks, workflows, starters, generations, and runs without loading full payloads.

Get one detail

Load schemas, defaults, hashes, outputs, usage, or errors for the selected resource.

Act on current state

Estimate and mutate only from the detail response, not a stale list summary.

Estimate and run a generation

Use the same task, optional model, and input for estimate and create. Creation is optional and requires the accepted estimate plus a stable caller-generated idempotency key.

{
  "tool": "list_console_generation_tasks",
  "arguments": {}
}

Run a workflow starter

Select a starter returned by discovery. Run it with the exact inputs and estimate_version returned by the preceding estimate.

{
  "tool": "list_public_workflow_starters",
  "arguments": {}
}

Run a Console workflow

Get the workflow before estimating or running it. Pass the returneddefinition_hash as expected_definition_hash; do not calculate the hash in the client.

{
  "tool": "list_console_workflows",
  "arguments": {}
}

Follow lifecycle and output

queuedActiveKeep polling. Cancellation can be requested.

runningActiveKeep polling. Cancellation is best effort.

succeededTerminalRead ordered output assets, structured data, and final usage.

failedTerminalInspect error and usage. Retry only after classifying the failure.

cancelledTerminalInspect final usage. The latest cancelled attempt may be retried.

manual_reviewTerminal for automationStop automated actions until status and billing are resolved.

Workflow runs follow the same operating rule: read the returned run ID until its status is terminal, then inspect outputs and errors before a retry or another paid action.

{
  "tool": "retry_console_generation",
  "arguments": {
    "generation_id": "gen_0123456789abcdef0123456789abcdef",
    "idempotency_key": "campaign-42-product-reveal-retry-1"
  }
}