Your First Agent

This tutorial walks you through spawning and interacting with a minimal agent.

Step 1: Start agentd

cargo run --bin agentd &
ash ping   # should print: pong

Step 2: Write a Manifest

Create my-agent.yaml:

apiVersion: scarab/v1
kind: AgentManifest
metadata:
  name: my-first-agent
  version: 1.0.0
  description: A minimal test agent.
spec:
  trust_level: sandboxed
  capabilities:
    - tool.invoke:echo
    - tool.invoke:agent.info
  lifecycle:
    restart_policy: never
    timeout_secs: 60
  command: /bin/sh
  args:
    - -c
    - "echo hello from my-first-agent"

Step 3: Validate the Manifest

ash validate my-agent.yaml
# Output: Manifest is valid

Validation is local; no daemon connection is required.

Step 4: Spawn the Agent

ash spawn my-agent.yaml
# Output: Spawned agent <UUID>

Step 5: List Running Agents

ash list
# ID                                    NAME              STATE    TRUST
# 550e8400-e29b-41d4-a716-446655440000  my-first-agent    Plan     sandboxed

Step 6: Inspect the Agent

ash info <UUID>

Step 7: Invoke a Tool on the Agent

ash tools invoke <UUID> echo '{"message": "hello"}'
# Output: {"message": "hello"}

Step 8: View the Audit Log

ash audit --agent <UUID>

Step 9: Terminate the Agent

ash kill <UUID>

Running the Example Agent

The example-agent binary demonstrates the full Plan→Act→Observe loop using lm.complete. It requires an OPENROUTER_API_KEY:

export OPENROUTER_API_KEY=sk-or-...
ash spawn etc/agents/example-agent.yaml
ash list
ash audit

The example agent will:

  1. Transition to Plan, declare a plan step
  2. Transition to Act, invoke lm.complete with its declared task
  3. Append an observation with the result
  4. Transition to Terminate

Next Steps