The Agents block runs a saved Crew Agent inside a Sandbox. It hands the agent a prompt, mints scoped tokens that let the sandbox call back into the workspace, streams the agent's run as NDJSON, and returns the response plus any files the agent produced.
Agents vs. Inference vs. Crew Agent
| Term | What it is |
|---|---|
| Agents block (this page) | A workflow block that dispatches a Crew Agent to a Sandbox and streams the result back. The block is named agents (plural). |
| Inference block | A single-shot LLM call. No memory, no multi-turn loop. See blocks/inference. |
| Crew Agent | The reusable agent definition this block runs. Defined in crew/agents. |
Configuration
Agent
The Agent dropdown loads from GET /api/workspaces/:workspaceId/agents and lists every Crew Agent in the current workspace. The block stores the agent's ID; the agent's model, skills, environment, and system prompt come from the Crew definition at run time.
Sandbox URL (optional)
The HTTP base URL of the sandbox runner. When empty, the block falls back to SANDBOX_URL from the workflow's environment variables, then to the server's SANDBOX_URL env. If none is set the run fails before dispatching.
Prompt
The user-side prompt for this run. The agent's own system prompt comes from its Crew definition — the prompt here is the per-run input, equivalent to a single user message.
How the block runs
The handler does the following on every execution:
- Mints three one-time tokens —
setup,run, andupload— and inserts hashed copies intocrewAgentOtpscoped to this execution. Setup and run expire in 10 minutes; upload expires in 60 minutes so the sandbox can still write back assets after the model is done. - Dispatches to
POST {sandboxUrl}/streamwith the agent's workspace URL, the three tokens, and the prompt. - Streams the sandbox's NDJSON response back into the workflow run. The block surfaces partial output through the run's stream so logs and downstream blocks see progress as it happens.
- Collects assets from the sandbox's
/root/workspace/assets/after writeback completes. They land on the block'sfilesoutput and can be passed to a Save File block to persist them.
Outputs
| Output | Type | Description |
|---|---|---|
response | string | Raw response body from the sandbox. |
files | file[] | Files in the sandbox's /root/workspace/assets/ directory after writeback. Drop into a Save File block to persist. |
The Agents block requires a running Sandbox. In self-hosted setups this is the assistant-sandbox service; the block authenticates with one-time tokens and the sandbox calls back into the workspace API to load the agent definition. See Sandbox for the runtime details.
Source
apps/actana/blocks/blocks/agents.ts— block definitionapps/actana/executor/handlers/agents/agents-handler.ts— runtime handlerapps/actana/lib/assistant-sandbox/— sandbox runtime