Agents

Agents are durable teammates inside a workspace. They have a name, description, public profile, instructions, mode, and runtime-owned configuration. Use them as reusable owners for recurring work, not just as interchangeable chat personas.

What makes a good agent role

A useful agent has a narrow purpose, a public profile that tells teammates when to use it, instructions that define evidence and autonomy boundaries, a clear handoff style, and an owner when the role needs updates.

Built-in and custom agents

Built-in workspace agents include roles such as Codex, Loopie, and Manus. These built-ins are not marketplace-publishable. Custom agents can be selected for publish and review operations when they are eligible.

Agent modes

Installed agent database modes use lowercase strings:

flash
pro
max
beast

GraphQL marketplace publish inputs use uppercase ExecutionMode enum values:

FLASH
PRO
MAX
BEAST

Clients must normalize the installed agent mode before calling publishAgentTemplateVersion(input:).

Marketplace model

The Agent Marketplace is backend-driven. The control plane uses AgentTemplate, AgentTemplateVersion, AgentTemplateLink, and AgentUpgradeRun. Installing a template creates a normal Agent row and records provenance through AgentTemplateLink.

Publishing scope

Agent templates can be public marketplace templates or workspace-scoped templates. Workspace publishing requires a workspace ID and owner/admin manage access. Public publishing is restricted to internal/admin accounts.

Versioning and upgrades

Template versions are anchored by Git tags. Runtime agent configuration stays DB-owned. Agents installed from templates can show installed/latest tags, repo IDs, upgrade availability, upgrade run status, conflicts, and preview/apply actions.

applyAgentUpgrade rejects stale preview runs when the installed template link no longer matches the run's from_version_id.

Next

To design a role from scratch, see Create an agent.