Agents
Saved agent definitions — system prompt, model endpoint, environment, skills, and MCP servers.
A Crew Agent is a saved, workspace-scoped definition that bundles a system prompt with everything an agent needs to run: a model endpoint, a named environment, a max-round budget, a set of skills, and a set of MCP servers.
The Agents block dispatches a Crew Agent to a Sandbox at run time. The same agent can also be invoked from outside a workflow through the agents API (see apps/actana/app/api/workspaces/[workspaceId]/agents/).
A Crew Agent is the definition. The Agents block is the runner. The Inference block is unrelated — it does not load a Crew Agent.
Anatomy
An agent row (agent table) has these fields:
| Field | Required | Notes |
|---|---|---|
name | Yes | Unique within the workspace. |
systemPrompt | Yes | Plain text. |
modelEndpointId | Yes | References workspace_model_endpoints. |
namedEnvironmentId | Yes | References workspace_named_environment. |
maxRounds | Default 10 | Cap on tool-calling iterations during a run. |
Plus two many-to-many tables:
agent_skill— attached skills.agent_mcp_server— attached MCP servers.
Creating an agent
Open Crew › Agents and click New Agent. The minimum fields the create dialog collects are:
- Name — must be unique in the workspace; a 409 collision surfaces inline on the field.
- Environment — pick a named environment. Required at create time.
- Model endpoint — pick a model endpoint. Required at create time.
After create, the dialog routes to the agent's detail page where you fill in the system prompt, attach skills, attach MCP servers, and adjust maxRounds.
Running an agent
There are two run paths and they share the same OTP-based bootstrap (crew_agent_otp table).
From a workflow — the Agents block
The Agents block dispatches the agent to a sandbox. On every run the executor mints three one-time tokens — setup, run, and upload — and the sandbox calls back into the workspace API to fetch the agent definition, environment script, and skills bundle. The block streams NDJSON output back into the workflow and collects assets from the sandbox's writeback at the end.
Directly — the agents API + tokens panel
For external callers, an agent's detail page exposes a tokens panel. You can mint long-lived OTP pairs and use them to enroll a sandbox without going through a workflow run. The same /config and /env endpoints that workflow runs hit are reused.
Skills + MCP servers attached to an agent
When an agent runs, the sandbox sees:
- The system prompt.
- The named environment's variables and setup script.
- Every attached skill bundle, materialized into the sandbox filesystem.
- Every attached MCP server, registered with the model so it can call MCP tools.
maxRounds caps the tool-calling loop. Reaching the cap ends the run and the partial output flows back through the stream.
Source
apps/actana/app/workspace/[workspaceId]/w/crew/agents/— UIapps/actana/app/api/workspaces/[workspaceId]/agents/— APIapps/actana/lib/crew/agent-config-serializer.ts— what the sandbox receivesapps/actana/lib/crew/otp.ts+lib/crew/otp-consume.ts— token mint + redeempackages/db/schema.ts—agent,agent_skill,agent_mcp_server,crew_agent_otp