ForjioHuudisIdentityPlugipayPaymentsCatentioAgentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streaming
Catentio Docs
⌘K

Agents

The Agents page at Dashboard → Agents is your view of the agent roster — every named Claude principal the runtime knows about, with its model, allowed tools, and recent run history. This is where you go to invoke an agent ad-hoc, inspect its config, or read the system prompt driving its behaviour.

The roster

Catentio ships with 19 named agents (builtins) covering content production, code work, research, and orchestration, plus any custom agents your workspace has created. Builtin agents come from app/agents/<slug>/ in the runtime repo; custom agents live in the database and require a runtime restart before they're dispatchable.

The list table shows, per agent: an avatar, the slug (linked to its detail page), description, model (with a badge when a specific default_model or reasoning level is pinned), prompt length, allowed-tools count, and a builtin/custom kind badge. Custom agents get an inline delete action; builtins can only be edited, never deleted.

The dashboard always reflects the live roster from GET /v1/agents — {total, builtin, custom} counts sit above the table.

Invoking an agent

Open an agent's detail page and use the Invoke panel: a single prompt textarea (placeholder "What should <slug> do?"), an Attach button for files, and a Run agent submit button.

  • Attach uploads files to the runtime host's /tmp via POST /api/v1/uploads; the saved paths are appended to the prompt as a manifest so the agent can Read them.
  • Submitting POSTs to /api/v1/cp/v1/runs with { agent: <slug>, transport: "rest", prompt: <text> }.
  • On success the panel shows an inline Run dispatched confirmation with a link to the run's detail page — it doesn't navigate you away automatically, and the run page you land on works by polling, not a live stream.

There's no "Advanced" panel with attached-context URLs, a run-mode toggle, or a model override on this form today — pin a model from the detail page's Model config button instead (see below).

The SDK/CLI invoke path is currently broken, and the SDKs have no working replacement. agents.invoke(slug, …) in all three SDKs, and catentio-saas agents invoke <slug> --message "…" in the CLI, call a control-plane route that proxies to a runtime endpoint that doesn't exist — the call 404s. There's also no runs.create() method in any SDK yet. The only way to start a run programmatically today is POST /v1/runs directly, with a body of { "agent": "<slug>", "prompt": "<text>" } (exactly one of prompt/message is required). From outside a browser, that's only reachable through the portal's cookie-authed /api/v1/cp/<path> proxy — there's no public catent.io/v1/... API. Track this as not currently usable rather than working around it.

The detail page

Beyond the invoke panel, an agent's detail page (GET /v1/agents/{slug}/detail) shows:

  • Header actions — Call and Chat open the chat-bubble panel preselected to this agent (a shortcut into the same REPL surface every dashboard page has, not a separate invoke path); Model config edits the pinned default_model and reasoning level; Voice config edits the agent's ElevenLabs voice_id, voice_model_id, and voice settings (stability / similarity / style / speaker-boost) via PATCH /v1/agents/{slug}/voice — works for builtins too; Edit opens the same create/edit sheet as New agent (see below), unless the deployment is in public/redacted visibility mode; Source links to the agent's module file on GitHub.
  • Stat cards — Model, effective model (the resolved default_model/reasoning pin), prompt length (characters), allowed-tools count, recent-runs count.
  • Description — the agent's short description field.
  • System prompt — the raw prompt text in a collapsible block (redacted in public/redacted visibility mode).
  • Allowed tools — the resolved tool slugs (linked to their Tools page entries), plus, for agents with an allowlist, the block/add breakdown (sensitive grants highlighted).
  • Recent runs — up to the 25 most recent runs (started, status, transport, duration, cost, run-id link).
  • Heartbeat — if a heartbeat is bound to this agent: enabled/disabled, interval, tasks-per-cycle, max-daily, cycle counters, and a View cycles → link to the heartbeat's own page. There's no inline "Configure" control here — that lives on the Heartbeats page itself.
  • Scheduled jobs — any cron jobs tied to this agent (schedule, enabled, next run).
  • Memory — total cold_memory entries scoped to this agent, broken down by type, with a Browse → link into Memory filtered to the agent.
  • Projects worked on — projects where this agent ran a subtask (template, status, subtask count, cost, last activity).

Creating and editing agents

New agent on the roster page, and Edit on a builtin or custom agent's detail page, open the same agentic-crud sheet used across the portal (Templates, Projects, and the rest): an Agentic tab where you describe the agent in plain language and the assistant drafts the fields, and a Manual tab to edit them directly — slug, model, prompt, description, allowed tool slugs, default model, reasoning. Builtins and customs share the sheet; for builtins, the tools field edits an add-only allowlist rather than replacing the resolved tool set outright. There's no PR/git-based editing flow — changes apply directly through the control plane (POST/PATCH /v1/agents).

Deleting an agent (custom agents only — builtins can't be deleted) leaves existing runs intact; no new run can dispatch that slug afterward.

Memory

Agents read and write to the runtime's memory layer during runs. Memory mutations (edit, delete, bulk-delete) are OTP-gated — the runtime returns an otp_required challenge that the caller must complete with x-catentio-otp-challenge / x-catentio-otp-code headers.

Voice agents

Any agent can carry an ElevenLabs voice config (voice_id, voice_model_id, voice_settings), editable from its detail page's Voice config button. Voice playback in the portal is preview-only; actual voice-channel routing happens in the runtime.

Next