Running Agents by Name

Once an agent is installed in the Agent Store, it can be spawned by name rather than by providing a manifest file path. This is the standard way to run production agents.

Spawn an installed agent

ash agent run <name>

Example:

ash agent run report-agent

agentd:

1. Looks up report-agent in the Agent Store.
2. Deserializes its stored manifest YAML.
3. Spawns the agent process from the install_dir, injecting SCARAB_AGENT_ID, SCARAB_SOCKET, SCARAB_TASK, and SCARAB_MODEL.
4. Returns the newly assigned agent ID.

Spawned agent 'report-agent' → 550e8400-e29b-41d4-a716-446655440000

Override the task at run time

Use --task to override the spec.task declared in the manifest for this particular run:

ash agent run report-agent \
  --task "Generate the Q4 2026 financial summary report"

The SCARAB_TASK environment variable is set to the override value. The manifest's stored spec.task is unchanged.

Difference from ash spawn

Use ash spawn for development and one-off runs. Use ash agent run for production workflows where the manifest has been reviewed and installed.

Agent-to-agent spawning by name

An agent can spawn another installed agent programmatically using the SpawnChildAgentByName IPC request. This requires the agent.spawn capability:

spec:
  capabilities:
    - agent.spawn

In Rust code:

#![allow(unused)]
fn main() {
use libagent::ipc::Request;

let req = Request::SpawnChildAgentByName {
    calling_agent_id: agent.id(),
    name: "worker-agent".to_string(),
    task_override: Some("Process batch #42".to_string()),
    cap_override: None,  // use worker-agent's full declared caps
};
let response = agent.send_request(req).await?;
}

cap_override, if provided, must be a subset of the calling agent's own capabilities; an agent cannot grant more than it has.

Monitoring spawned agents

After spawning, use the returned agent ID to monitor progress:

# Check lifecycle state
ash info <agent-id>

# Stream observation log
ash obs query <agent-id> --limit 100

# View full execution timeline
ash replay timeline <agent-id>

Stopping a named agent

ash kill <agent-id>

This sends a Terminate lifecycle transition regardless of how the agent was spawned.