Skip to content
AlumiaDocs

Search docs

Find pages, headings, and concepts. Press ⌘K or Ctrl+K to toggle.

Agents

AI agents with a system prompt, a chosen model, scoped tools, and managed reliability.

Open in ChatGPTOpen in Claude

An agent is the smallest unit of execution in Alumia. Every agent has a system prompt, a chosen model, a set of tools it's allowed to call, and a session that holds its conversation history.

Anatomy of an agent

FieldPurpose
System promptDefines identity, behavior, and constraints.
ModelOne of 38 visible models across 14 providers. Swap any time from the agent detail page — and an agent can switch its own model at runtime with set_agent_model when you explicitly ask it to.
Runtime settingsOptional per-agent settings in agent config: Fast mode maps supported models to a faster catalog sibling at chat time; Reasoning effort (low / medium / high) applies to OpenAI reasoning-capable models only.
ToolsBuilt-in tools and connector-backed tools the agent can call.
SkillsOptional platform expansion skills that gate bundled tool sets.
MemoryLong-term context stored in pgvector and recalled per query.
WorkspaceA primary workspace, optionally shared into others via agent_workspaces. Ala is visible everywhere.

How an agent runs

Agents run on the AI SDK v6 (ai package) under the hood. Calls flow through provider-specific adapters (@ai-sdk/anthropic, @ai-sdk/openai, …) with retries, streaming, and tool-call handling managed by the platform.

When you send a message, the runtime builds the prompt, attaches available tools, streams the response, and emits canvas activity events live so collaborators see what's happening as it happens.

The default agent: Ala

Every org ships with Ala, a shared agent visible from every workspace and every project. Ala is org-scoped, active by default, and can't be deleted. Use Ala when you want a single agent that already knows about your whole org; create new agents when you want specialised behavior. A created agent can be shared into multiple workspaces when several teams need it.

Canvas-aware behaviour

The platform's system prompt instructs every agent on how to compose canvas blocks well. Specifically:

  • Three-path block model. Default to data_block with a typed DataSpec for structured displays. Use show only for the 13 interactive system primitives. Use app_create only when the user explicitly asks for a custom app.
  • Search before creating. Call search_blocks (or list_blocks for a full inventory) before emitting a new block of the same purpose — update the existing block instead of duplicating.
  • Compose workboards. When a response needs several related blocks, call compose_canvas once so the user gets a complete grouped workboard on the existing canvas. Use recompose_canvas to update an existing grouped workboard rather than creating a second copy.
  • Patch, don't replace. Use search_block to find JSON Pointer paths, then update_block with patch for surgical edits.
  • Variant whitelists (default | secondary | destructive | outline | ghost | muted for buttons, success | warning | destructive | info | muted for status, etc.) — agents never invent variants.
  • 2026 colour palette — 12 curated hex values (slate, azure, iris, emerald, sage, amber, honey, rose, violet, teal, fuchsia, cloud) for chart series, callout markers, or any field that takes a hex. No neon, no invented colours.
  • Simplify ruthlessly — agents strip optional fields when empty, omit filler copy ("Welcome to your…", "Discover amazing…"), keep tables to 3–5 columns unless the user asks for more, use font-medium/font-semibold for headings (never font-bold), and reserve rose/emerald for genuine errors/successes.
  • Social posts include media. Tweets, X / LinkedIn / Bluesky / Threads drafts call image_save first and attach the resulting fileId to media.fileId. A tweet without media looks unfinished.
  • No external https:// URLs in image fields. The agent saves images via image_save and references them by fileId; the renderer resolves to a CORS-safe URL.