agent-worker

name	agent-worker
description	Create and manage AI agent sessions with multiple backends (SDK, Claude CLI, Codex, Cursor). Also supports multi-agent workflows with shared context, @mention coordination, and collaborative voting. Use for "start agent session", "create worker", "run agent", "multi-agent workflow", "agent collaboration", "test with tools", or when orchestrating AI conversations programmatically.

Agent Worker

Who You Are

You build AI-powered workflows—from simple Q&A to complex multi-agent collaboration.

Two modes, one model:

• Agent Mode: Run individual agents via CLI commands
• Workflow Mode: Orchestrate multiple agents via YAML

Both modes share the same context system: agents communicate through channels (@mentions) and documents (shared workspace). Everything is namespaced by workflow:tag.

---

Quick Decision Guide

I Want To...	Use This
Chat with an AI agent	Agent Mode (CLI)
Test tools/prompts quickly	Agent Mode with -b mock
Run multiple agents manually	Workflow Mode (YAML)
Define structured multi-agent tasks	Workflow Mode (YAML)
Automate repeatable workflows	Workflow Mode (YAML)

---

🤖 Agent Mode

Run individual agents from the command line.

Quick Start

# Create an agent (auto-named: a0, a1, ...)
agent-worker new -m anthropic/claude-sonnet-4-5
# → a0

# Send a message
agent-worker send a0 "What is 2+2?"

# View conversation
agent-worker peek

# Create a second agent (shares channel)
agent-worker new coder
agent-worker send @global "@a0 @coder collaborate on this"

# Stop agents
agent-worker stop a0 coder

Organizing Agents (workflow:tag)

Group agents into workflows using YAML definitions:

# review.yaml
agents:
  reviewer:
    backend: claude
    system_prompt: You are a code reviewer.
  coder:
    backend: cursor
    system_prompt: You fix issues.

# Run workflow agents (workflow name from YAML)
agent-worker run review.yaml

# Send to specific agent in workflow
agent-worker send reviewer@review "Check this code"

# Multiple isolated instances (tags)
agent-worker run review.yaml --tag pr-123
agent-worker run review.yaml --tag pr-456

# Each tag has independent context
agent-worker send reviewer@review:pr-123 "LGTM"
agent-worker peek @review:pr-123  # Only sees pr-123 messages

Note: agent-worker new only creates standalone agents in the global workflow. Use YAML for workflow agents.

Target syntax:

• alice → standalone (alice@global:main)
• alice@review → agent in review workflow (alice@review:main)
• alice@review:pr-123 → full specification
• @review → workflow reference (for broadcast/listing)
• @review:pr-123 → specific workflow instance

Context isolation:

.workflow/
├── global/main/        # Standalone agents (default)
├── review/main/        # review workflow, default tag
└── review/pr-123/      # review workflow, pr-123 tag

Agent Commands

# Lifecycle
agent-worker new [name] [options]        # Create standalone agent
agent-worker ls [target]                 # List agents (default: global)
agent-worker ls --all                    # List all agents from all workflows
agent-worker status <target>             # Check status
agent-worker stop <target>               # Stop agent
agent-worker stop @workflow:tag          # Stop all in workflow:tag

# Interaction
agent-worker send <target> <message>
agent-worker peek [target] [--all] [--find <text>]

# Per-agent operations
agent-worker stats <target>              # Statistics
agent-worker export <target>             # Export transcript
agent-worker clear <target>              # Clear history

# Scheduling (periodic wakeup)
agent-worker schedule <target> set <interval> [--prompt "..."]
agent-worker schedule <target> get
agent-worker schedule <target> clear

# Shared documents
agent-worker doc read <target>
agent-worker doc write <target> --content "..."
agent-worker doc append <target> --file notes.txt

Backend Options

agent-worker new -m anthropic/claude-sonnet-4-5  # SDK (default)
agent-worker new -b claude                       # Claude CLI
agent-worker new -b cursor                       # Cursor Agent
agent-worker new -b mock                         # Testing (no API)

Note: Tool management (add, mock, import) only works with SDK backend.

Examples

Quick testing without API keys:

agent-worker new -b mock
agent-worker send a0 "Hello"

Scheduled monitoring agent:

agent-worker new monitor --wakeup 30s --prompt "Check CI status"

Multi-agent code review (using YAML workflow):

# review.yaml
agents:
  reviewer:
    backend: claude
    system_prompt: You are a code reviewer.
  coder:
    backend: cursor
    system_prompt: You fix issues.

# Run workflow (workflow name from YAML)
agent-worker run review.yaml --tag pr-123

# Interact with agents
agent-worker send reviewer@review:pr-123 "Review recent changes"
agent-worker peek @review:pr-123

---

📋 Workflow Mode

Define multi-agent collaboration via YAML.

Quick Start

# review.yaml
agents:
  reviewer:
    backend: claude
    system_prompt: You are a code reviewer. Provide constructive feedback.

  coder:
    backend: cursor
    model: sonnet-4.5
    system_prompt: You implement code changes based on feedback.

kickoff: |
  @reviewer Review the recent changes and provide feedback.
  @coder Implement the suggested improvements.

# Run once and exit
agent-worker run review.yaml

# Keep agents alive
agent-worker start review.yaml

# With specific tag
agent-worker run review.yaml --tag pr-123

Workflow Structure

# Full workflow file structure
name: code-review # Optional (defaults to filename)

# Agent definitions
agents:
  alice:
    backend: sdk | claude | cursor | codex | mock
    model: anthropic/claude-sonnet-4-5 # Required for SDK backend
    system_prompt: |
      You are Alice, a senior code reviewer.
    # OR
    system_prompt_file: ./prompts/alice.txt

    tools: [bash, read, write] # CLI backend tool names
    max_tokens: 8000
    max_steps: 20

  bob:
    backend: claude
    system_prompt: You are Bob, a helpful coder.

# Context configuration (shared channel + documents)
context:
  provider: file
  config:
    # Ephemeral (default) - cleared on shutdown
    dir: ./.workflow/${{ workflow.name }}/${{ workflow.tag }}/

    # OR persistent - survives shutdown
    bind: ./data/${{ workflow.tag }}/

# Setup commands (run before kickoff)
setup:
  - shell: git log --oneline -10
    as: recent_commits # Store output in variable

  - shell: git diff main...HEAD
    as: changes

# Kickoff message (starts the workflow)
kickoff: |
  @alice Review these changes:

  Recent commits:
  ${{ recent_commits }}

  Diff:
  ${{ changes }}

  @bob Stand by for implementation.

Variable Interpolation

Use ${{ variable }} syntax in kickoff and setup:

setup:
  - shell: echo "pr-${{ env.PR_NUMBER }}"
    as: branch_name

kickoff: |
  Workflow: ${{ workflow.name }}
  Tag: ${{ workflow.tag }}
  Branch: ${{ branch_name }}

Available variables:

• ${{ workflow.name }} - Workflow name
• ${{ workflow.tag }} - Instance tag
• ${{ env.VAR }} - Environment variable
• ${{ task_output }} - Setup task output (via as:)

Coordination Patterns

Sequential handoff:

kickoff: |
  @alice Start the task.

Alice finishes and mentions: "@bob your turn"

Parallel execution:

kickoff: |
  @alice @bob @charlie All review this code.

Document-based collaboration:

agents:
  researcher:
    system_prompt: Research and write findings to the shared document.

  summarizer:
    system_prompt: Read the document and create a concise summary.

context:
  provider: file
  config:
    bind: ./results/ # Persistent across runs

Workflow Examples

PR Review Workflow:

# review.yaml
agents:
  reviewer:
    backend: claude
    system_prompt: |
      Review code for:
      - Bugs and logic errors
      - Code style and readability
      - Performance issues

setup:
  - shell: gh pr diff ${{ env.PR_NUMBER }}
    as: diff

kickoff: |
  @reviewer Review this PR:

  ${{ diff }}

  Provide clear, actionable feedback.

PR_NUMBER=123 agent-worker run review.yaml --tag pr-123

Research & Summarize:

# research.yaml
agents:
  researcher:
    backend: sdk
    model: anthropic/claude-sonnet-4-5
    system_prompt: |
      Research topics thoroughly.
      Write detailed findings to the shared document.

  summarizer:
    backend: sdk
    model: anthropic/claude-haiku-4-5
    system_prompt: |
      Read the document and create:
      - Executive summary (3-5 bullet points)
      - Key findings
      - Recommendations

context:
  provider: file
  config:
    bind: ./research-output/

kickoff: |
  @researcher Research "${{ env.TOPIC }}" and document findings.
  @summarizer Wait for research to complete, then create summary.

TOPIC="AI agent frameworks" agent-worker run research.yaml

Test Generation:

# test-gen.yaml
agents:
  analyzer:
    model: anthropic/claude-sonnet-4-5
    system_prompt: Analyze code and identify test cases.

  generator:
    model: anthropic/claude-sonnet-4-5
    system_prompt: Generate test code based on identified cases.

setup:
  - shell: cat src/main.ts
    as: code

kickoff: |
  @analyzer Analyze this code and identify test cases:
  ${{ code }}

  @generator Generate comprehensive tests based on the analysis.

Consensus Decision:

# consensus.yaml
agents:
  alice:
    system_prompt: You are a cautious reviewer.

  bob:
    system_prompt: You are an optimistic reviewer.

  charlie:
    system_prompt: You balance caution and optimism.

setup:
  - shell: git diff
    as: changes

kickoff: |
  @alice @bob @charlie Review these changes:
  ${{ changes }}

  Each provide your assessment. Use proposal tools to vote on merging.

---

Core Concepts

Channels (Communication)

All agents in a workflow share a channel. Messages route via @mentions:

# Route to specific agent
agent-worker send alice "analyze this"

# Route to multiple agents (workflow broadcast with @mentions)
agent-worker send @review "@alice @bob collaborate on this"

# Broadcast to workflow (no @mention)
agent-worker send @review "Status update"

Available tools (in agent's system prompt):

• channel_send - Send message to channel
• channel_read - Read recent messages
• inbox_read - Read own @mentions

Documents (Shared State)

Agents can read/write to a shared document:

# Manual document management
agent-worker doc read @review:pr-123
agent-worker doc write @review:pr-123 --content "Analysis complete"
agent-worker doc append @review:pr-123 --file results.txt

Available tools (in agent's system prompt):

• document_read - Read current document
• document_write - Overwrite document
• document_append - Append to document

Proposals & Voting

For collaborative decisions:

Available tools:

• proposal_create - Create proposal (election, decision, approval)
• vote - Cast vote on proposal
• proposal_status - Check results

Resolution types:

• plurality - Most votes wins
• majority - >50% required
• unanimous - All votes must agree

Example usage in agent's tool calls:

{
  "name": "proposal_create",
  "arguments": {
    "title": "Merge PR #123",
    "type": "approval",
    "resolution": "majority"
  }
}

---

Scheduling (Periodic Wakeup)

Agents can wake up periodically when idle:

Mode	Format	Behavior
Interval	60000, 30s, 5m, 2h	Fires after idle. Resets on activity.
Cron	0 */2 * * *	Fixed schedule. NOT reset by activity.

# At creation
agent-worker new --wakeup 5m
agent-worker new --wakeup "0 */2 * * *" --wakeup-prompt "Check for updates"

# Runtime management
agent-worker schedule <target> set 5m
agent-worker schedule <target> set "0 */2 * * *" -p "Health check"
agent-worker schedule <target> get
agent-worker schedule <target> clear

---

Tool Management (SDK Backend Only)

Specifying Tools at Creation

Tools are specified when creating an agent using the --tool parameter:

# Create agent with custom tools
agent-worker new alice --tool ./my-tools.ts

# Combine with skills
agent-worker new alice --skill ./skills --tool ./tools.ts

Tool File Format

// my-tools.ts
export default [
  {
    name: "search_docs",
    description: "Search documentation",
    parameters: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query" },
      },
      required: ["query"],
    },
    needsApproval: false, // Optional: require approval before execution
    execute: async (args) => {
      return { results: ["doc1", "doc2"] };
    },
  },
];

Mocking Tools (Testing)

# Mock tool response for testing
agent-worker mock tool get_weather '{"temp": 72, "condition": "sunny"}'

# View agent feedback/observations
agent-worker feedback alice

Approval Workflow

For tools marked needsApproval:

agent-worker send a0 "Delete /tmp/test.txt"
agent-worker pending
agent-worker approve <id>
agent-worker deny <id> -r "Path not allowed"

---

Model Formats

SDK backend supports multiple formats:

# Gateway format (recommended)
agent-worker new -m openai/gpt-4.5
agent-worker new -m anthropic/claude-sonnet-4-5

# Provider-only (uses frontier model)
agent-worker new -m openai
agent-worker new -m anthropic

# Direct provider format
agent-worker new -m deepseek:deepseek-chat

Check available providers:

agent-worker providers

---

Programmatic Usage (SDK)

For TypeScript/JavaScript integration:

import { AgentWorker } from "agent-worker";

const session = new AgentWorker({
  model: "anthropic/claude-sonnet-4-5",
  system: "You are a helpful assistant.",
  tools: [
    /* your tools */
  ],
});

// Send message
const response = await session.send("Hello");
console.log(response.content);
console.log(response.toolCalls);
console.log(response.usage);

// Stream response
for await (const chunk of session.sendStream("Tell me a story")) {
  process.stdout.write(chunk);
}

// State management
const state = session.getState();
// Later: restore from state

With Skills

import { AgentWorker, createSkillTool } from "agent-worker";
import { createBashTool } from "bash-tool";

// Discover skills and collect files for bash sandbox
const { skill, files, instructions } = await createSkillTool({
  skillsDirectory: ".agents/skills",
});

// Create bash tool with skill files available
const { tools } = await createBashTool({ files, extraInstructions: instructions });

const session = new AgentWorker({
  model: "anthropic/claude-sonnet-4-5",
  system: "You are a helpful assistant.",
  tools: { skill, ...tools },
});

---

Troubleshooting

Issue	Solution
"No active agent"	Run agent-worker new first
"Agent not found"	Check agent-worker ls
"Tool management not supported"	Use SDK backend (default)
"Provider not loaded"	Check API key: agent-worker providers
Agent not responding	Check status: agent-worker status <target>
No response in peek	Agent still processing. Wait and retry.
Workflow file errors	Validate YAML syntax

---

Command Reference

# Agent Management
agent-worker new [name]              Create agent (auto-names if omitted)
  -m, --model <model>                Model (SDK backend)
  -b, --backend <type>               Backend: sdk, claude, cursor, codex, mock
  -s, --system <prompt>              System prompt
  -f, --system-file <path>           System prompt from file
  --tool <file>                      Import MCP tools from file (SDK backend)
  --wakeup <interval|cron>           Periodic wakeup schedule
  --wakeup-prompt <text>             Prompt for wakeup
  --idle-timeout <ms>                Idle timeout (0 = no timeout)

agent-worker ls [target]             List agents (default: global)
  --all                              Show agents from all workflows

agent-worker status <target>         Check agent status
agent-worker stop <target>           Stop agent
  --all                              Stop all agents
  Target: agent, agent@workflow:tag, or @workflow:tag

# Communication
agent-worker send <target> <message> Send to agent or workflow
  Target examples:
    alice                            Send to alice@global:main
    alice@review                     Send to alice@review:main
    alice@review:pr-123              Send to specific workflow:tag
    @review                          Broadcast to review workflow
    @review:pr-123                   Broadcast to workflow:tag

agent-worker peek [target]           View channel messages
  Target: agent@workflow:tag or @workflow:tag (default: @global)
  --all                              Show all messages
  -n, --last <count>                 Show last N messages
  --find <text>                      Search messages

# Per-agent Operations
agent-worker stats <target>          Show statistics
agent-worker export <target>         Export transcript
agent-worker clear <target>          Clear history

# Scheduling
agent-worker schedule <target> set <interval> [options]
agent-worker schedule <target> get
agent-worker schedule <target> clear

# Documents
agent-worker doc read <target>
agent-worker doc write <target> --content <text>
agent-worker doc append <target> --file <path>
  Target: @workflow:tag (e.g., @review:pr-123)

# Testing & Debugging
agent-worker mock tool <name> <response>  Mock tool response (SDK backend)
agent-worker feedback [target]            View agent feedback/observations

# Approvals
agent-worker pending                 List pending approvals
agent-worker approve <id>            Approve tool call
agent-worker deny <id> -r <reason>   Deny tool call

# Workflows (YAML)
agent-worker run <file>              Run workflow (exit on complete)
  --tag <tag>                        Workflow instance tag (default: main)
  --json                             JSON output
  --debug                            Show debug logs
  --feedback                         Enable feedback tool
  Note: Workflow name inferred from YAML 'name' field or filename

agent-worker start <file>            Start workflow (keep running)
  --tag <tag>                        Workflow instance tag (default: main)
  --background                       Run in background
  Note: Workflow name inferred from YAML 'name' field or filename

# Utilities
agent-worker providers               Check SDK providers
agent-worker backends                Check available backends

---

Remember

Two modes, same model:

• Agent Mode: Manual CLI control, perfect for exploration
• Workflow Mode: Declarative YAML, perfect for automation

Both use:

• workflow:tag for namespacing and isolation
• Channels for @mention-based communication
• Documents for shared state
• Proposals for collaborative decisions

Choose the mode that fits your task. Mix and match as needed.