> ## Documentation Index
> Fetch the complete documentation index at: https://klaw.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Agents
> Understanding the core building block of klaw
## 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
```bash theme={null}
# 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/`:
```toml theme={null}
# ~/.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
Agent definition is created and stored. No resources consumed yet.
When a message arrives for the agent, it's activated with its LLM provider, tools, and system prompt.
Agent enters the tool-use loop: receive input → LLM decision → tool execution → repeat.
After completing a task, agent maintains conversation history but releases LLM connection.
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:
```toml theme={null}
[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
```bash theme={null}
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
```bash theme={null}
klaw describe agent coder
```
Output:
```yaml theme={null}
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
```bash theme={null}
klaw delete agent researcher
```
## Agent Communication
Agents receive work through **channels**:
Direct interaction via `klaw chat`
Messages in Slack channels/threads
REST API calls for programmatic access
Dispatched tasks from controller
## Multi-Agent Patterns
### Specialized Agents
Create agents for specific domains:
```bash theme={null}
# 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:
```json theme={null}
{
"tool": "delegate",
"input": {
"task": "Create React components for the user dashboard",
"tools": ["read", "write", "edit", "glob", "bash"]
}
}
```
Or `agent_spawn` for persistent bindings:
```json theme={null}
{
"tool": "agent_spawn",
"input": {
"name": "frontend-worker",
"task": "Create React components for the user dashboard"
}
}
```
## Agent Runtime Modes
Agent runs as a local process with direct system access:
```toml theme={null}
runtime = "process"
```
* Full filesystem access
* Direct command execution
* Fastest performance
Agent runs in an isolated container:
```toml theme={null}
runtime = "docker"
[docker]
image = "klaw-agent:latest"
volumes = ["/data:/workspace"]
```
* Sandboxed environment
* Reproducible execution
* Resource limits
## Best Practices
Give each agent a specific, well-defined task. Specialized agents perform better than generalists.
**Good**: "API development and testing"
**Bad**: "Do everything"
Only give agents the tools they actually need. Avoid granting bash access unless necessary.
Constrain agents to specific directories to prevent unintended file modifications.
Match model capabilities to task complexity. Use Sonnet for most tasks, Opus for complex reasoning.
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.
Add `require_approval = ["bash", "write"]` to agents that modify files or run commands. This adds a human-in-the-loop check before execution.
## Next Steps
Learn about the tools agents can use
Compose capabilities with skills