Agents

What is an Agent?

An agent is the fundamental unit of deployment in klaw. It’s an autonomous AI entity that can:

Understand natural language instructions
Make decisions about how to accomplish tasks
Use tools to interact with systems and data
Maintain conversation context
Learn from interactions through memory

Think of agents like pods in Kubernetes—they’re the smallest deployable units that encapsulate the logic and capabilities needed to perform work.

Agent Architecture

┌─────────────────────────────────────────────────────┐
│                     AGENT                           │
│  ┌───────────────────────────────────────────────┐  │
│  │               LLM Provider                    │  │
│  │  (Claude, GPT-4, Gemini, etc.)               │  │
│  └───────────────────┬───────────────────────────┘  │
│                      │                              │
│  ┌───────────────────▼───────────────────────────┐  │
│  │            Conversation History               │  │
│  │  (Thread-aware, per-channel)                 │  │
│  └───────────────────┬───────────────────────────┘  │
│                      │                              │
│  ┌───────────────────▼───────────────────────────┐  │
│  │              Tools Registry                   │  │
│  │  [bash] [read] [write] [web] [...]           │  │
│  └───────────────────┬───────────────────────────┘  │
│                      │                              │
│  ┌───────────────────▼───────────────────────────┐  │
│  │              System Prompt                    │  │
│  │  (Identity + Skills + Memory)                │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

Creating Agents

Using the CLI

# Create a basic agent
klaw create agent coder --model claude-sonnet-4-20250514

# Create with specific skills
klaw create agent researcher \
  --model claude-sonnet-4-20250514 \
  --skills web-search,browser

# Create with custom workdir
klaw create agent devops \
  --model gpt-4o \
  --skills docker,git \
  --workdir /home/user/infrastructure

Agent Definition File

Agents are stored as TOML files in ~/.klaw/agents/:

# ~/.klaw/agents/researcher.toml
name = "researcher"
model = "claude-sonnet-4-20250514"
task = "Research and analyze information from the web"
tools = ["web-search", "browser", "read", "write"]
workdir = "/home/user/research"
runtime = "process"
created_at = 2024-12-14T10:00:00Z

[config]
temperature = 0.7
max_tokens = 4096

Agent Lifecycle

Creation

Agent definition is created and stored. No resources consumed yet.

Activation

When a message arrives for the agent, it’s activated with its LLM provider, tools, and system prompt.

Processing

Agent enters the tool-use loop: receive input → LLM decision → tool execution → repeat.

Idle

After completing a task, agent maintains conversation history but releases LLM connection.

Termination

Agent is deleted or cluster shuts down. History can be preserved or discarded.

Agent Properties

Property	Description	Required	Default
`name`	Unique identifier for the agent	Yes	—
`model`	LLM model to use	Yes	—
`task`	Description of the agent’s purpose	No	—
`tools`	Allowlist of tools the agent can use	No	All tools
`workdir`	Working directory for file operations	No	CWD
`runtime`	Execution environment (`process` or `docker`)	No	`process`
`max_iterations`	Maximum agent loop iterations	No	`50`
`require_approval`	Tool names requiring user confirmation	No	`[]`

Agent Configuration

Per-agent settings in config.toml let you customize tool access, iteration limits, and approval requirements for each agent independently:

[agent.default]
tools = ["bash", "read", "write", "edit", "glob", "grep", "web_fetch", "web_search"]
max_iterations = 50
require_approval = ["bash"]

[agent.researcher]
tools = ["read", "glob", "grep", "web_fetch", "web_search"]
max_iterations = 30

[agent.coder]
tools = ["bash", "read", "write", "edit", "glob", "grep"]
max_iterations = 100
require_approval = ["bash", "write"]

Tool filtering restricts which tools an agent can use. If tools is omitted, the agent has access to all registered tools. When specified, only the listed tools are available — the agent cannot call tools outside its allowlist. Approval gating requires user confirmation before specific tools execute. When a tool in the require_approval list is called, the user sees a prompt and must approve or deny execution.

Managing Agents

List Agents

klaw get agents

Output:

NAME        MODEL                       SKILLS              STATUS
coder       claude-sonnet-4-20250514   git,code-exec       Ready
researcher  claude-sonnet-4-20250514   web-search,browser  Ready
devops      gpt-4o                      docker,bash         Ready

Describe an Agent

klaw describe agent coder

Output:

Name:       coder
Model:      claude-sonnet-4-20250514
Task:       Write and debug code
Skills:     git, code-exec
Workdir:    /home/user/projects
Runtime:    process
Created:    2024-12-14T10:00:00Z
Status:     Ready
Sessions:   12
Last Used:  2024-12-14T15:30:00Z

Delete an Agent

klaw delete agent researcher

Agent Communication

Agents receive work through channels:

CLI

Direct interaction via klaw chat

Slack

Messages in Slack channels/threads

API

REST API calls for programmatic access

Tasks

Dispatched tasks from controller

Multi-Agent Patterns

Specialized Agents

Create agents for specific domains:

# Frontend specialist
klaw create agent frontend \
  --model claude-sonnet-4 \
  --skills code-exec \
  --task "React/TypeScript frontend development"

# Backend specialist
klaw create agent backend \
  --model claude-sonnet-4 \
  --skills code-exec,database \
  --task "Go/Python backend development"

# DevOps specialist
klaw create agent devops \
  --model gpt-4o \
  --skills docker,git \
  --task "Infrastructure and deployment"

Agent Spawning

klaw supports two forms of sub-agent creation: agent_spawn — Creates persistent agent bindings for the orchestrator. These are long-lived agents that can be routed to via @agent syntax. delegate — Spawns ephemeral sub-agents inline during a conversation. The sub-agent executes immediately, and its result is returned directly to the parent. This is the primary mechanism for multi-step task decomposition.

User: "Build a full-stack application with tests"
      │
      ▼
┌─────────────────┐
│  Main Agent     │
│  (Coordinator)  │
└────────┬────────┘
         │ delegate
    ┌────┼────┐
    │    │    │
    ▼    ▼    ▼
┌──────┐┌──────┐┌──────┐
│Front ││Back  ││Tests │
│end   ││end   ││      │
└──────┘└──────┘└──────┘
   │        │       │
   └────────┴───────┘
         │
    Results returned
    to main agent

Use the delegate tool for inline sub-agents:

{
  "tool": "delegate",
  "input": {
    "task": "Create React components for the user dashboard",
    "tools": ["read", "write", "edit", "glob", "bash"]
  }
}

Or agent_spawn for persistent bindings:

{
  "tool": "agent_spawn",
  "input": {
    "name": "frontend-worker",
    "task": "Create React components for the user dashboard"
  }
}

Agent Runtime Modes

Process (Default)
Docker

Agent runs as a local process with direct system access:

runtime = "process"

Full filesystem access
Direct command execution
Fastest performance

Agent runs in an isolated container:

runtime = "docker"

[docker]
image = "klaw-agent:latest"
volumes = ["/data:/workspace"]

Sandboxed environment
Reproducible execution
Resource limits

Best Practices

Define clear purposes

Give each agent a specific, well-defined task. Specialized agents perform better than generalists.Good: “API development and testing” Bad: “Do everything”

Minimize tool permissions

Only give agents the tools they actually need. Avoid granting bash access unless necessary.

Set appropriate workdirs

Constrain agents to specific directories to prevent unintended file modifications.

Use appropriate models

Match model capabilities to task complexity. Use Sonnet for most tasks, Opus for complex reasoning.

Set cost budgets

Use max_session_cost to cap spending per session. Start conservative (e.g., $5.00) and adjust based on your workload. The agent stops gracefully when the budget is reached.

Require approval for risky tools

Add require_approval = ["bash", "write"] to agents that modify files or run commands. This adds a human-in-the-loop check before execution.

Getting Started

Core Concepts

Guides

Configuration

Architecture

CLI Reference

Resources

What is an Agent?

Agent Architecture

Creating Agents

Using the CLI

Agent Definition File

Agent Lifecycle

Agent Properties

Agent Configuration

Managing Agents

List Agents

Describe an Agent

Delete an Agent

Agent Communication

CLI

Slack

API

Tasks

Multi-Agent Patterns

Specialized Agents

Agent Spawning

Agent Runtime Modes

Best Practices

Next Steps

Tools

Skills

Getting Started

Core Concepts

Guides

Configuration

Architecture

CLI Reference

Resources

​What is an Agent?

​Agent Architecture

​Creating Agents

​Using the CLI

​Agent Definition File

​Agent Lifecycle

​Agent Properties

​Agent Configuration

​Managing Agents

​List Agents

​Describe an Agent

​Delete an Agent

​Agent Communication

CLI

Slack

API

Tasks

​Multi-Agent Patterns

​Specialized Agents

​Agent Spawning

​Agent Runtime Modes

​Best Practices

​Next Steps

Tools

Skills

What is an Agent?

Agent Architecture

Creating Agents

Using the CLI

Agent Definition File

Agent Lifecycle

Agent Properties

Agent Configuration

Managing Agents

List Agents

Describe an Agent

Delete an Agent

Agent Communication

Multi-Agent Patterns

Specialized Agents

Agent Spawning

Agent Runtime Modes

Best Practices

Next Steps