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

bash

# 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:

yaml

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

bash

# 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

bash

# 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

bash

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:

bash

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

Scheduled monitoring agent:

bash

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

Multi-agent code review (using YAML workflow):

yaml

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

bash

# 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

yaml

# 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.

bash

# 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

yaml

# 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:

yaml

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:

yaml

kickoff: |
  @alice Start the task.

Alice finishes and mentions: "@bob your turn"

Parallel execution:

yaml

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

Document-based collaboration:

yaml

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:

yaml

# 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.

bash

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

Research & Summarize:

yaml

# 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.

bash

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

Test Generation:

yaml

# 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:

yaml

# 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

bash

# 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:

bash

# 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:

json

{
  "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.

bash

# 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:

bash

# 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

typescript

// 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)

bash

# 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

bash

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:

bash

# 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:

bash

agent-worker providers

Programmatic Usage (SDK)

For TypeScript/JavaScript integration:

typescript

import { AgentSession } from 'agent-worker'

const session = new AgentSession({
  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

typescript

import { AgentSession, SkillsProvider, createSkillsTool } from 'agent-worker'

const skillsProvider = new SkillsProvider()
await skillsProvider.scanDirectory('.agents/skills')

const session = new AgentSession({
  model: 'anthropic/claude-sonnet-4-5',
  system: 'You are a helpful assistant.',
  tools: [createSkillsTool(skillsProvider)]
})

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.

agent-worker

NPX Install

Tags

SKILL.md Content

Agent Worker

Who You Are

Quick Decision Guide

🤖 Agent Mode

Quick Start

Organizing Agents (workflow:tag)

Agent Commands

Backend Options

Examples

📋 Workflow Mode

Quick Start

Workflow Structure

Variable Interpolation

Coordination Patterns

Workflow Examples

Core Concepts

Channels (Communication)

Documents (Shared State)

Proposals & Voting

Scheduling (Periodic Wakeup)

Tool Management (SDK Backend Only)

Specifying Tools at Creation

Tool File Format

Mocking Tools (Testing)

Approval Workflow

Model Formats

Programmatic Usage (SDK)

With Skills

Troubleshooting

Command Reference

Remember