> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openpawz.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Agents are the core of Pawz — autonomous AI personas that chat, use tools, remember context, and collaborate.

# Agents

Agents are the core of Pawz — autonomous AI personas that chat, use tools, remember context, and collaborate.

## Creating an agent

1. Go to **Agents** in the sidebar
2. Click **Create Agent**
3. Fill in the basics:
   * **Name** — displayed in chat and dock
   * **Avatar** — choose from 50 sprite avatars
   * **Color** — pick from 7 accent colors
   * **Bio** — short description of what this agent does

## Templates

Templates pre-configure skills and personality for common use cases:

| Template      | Skills                                           | Tone       | Initiative | Detail     |
| ------------- | ------------------------------------------------ | ---------- | ---------- | ---------- |
| **General**   | web\_search, web\_fetch, read, write             | balanced   | balanced   | balanced   |
| **Research**  | web\_search, web\_fetch, read, write, browser    | formal     | proactive  | thorough   |
| **Creative**  | web\_search, web\_fetch, read, write             | casual     | proactive  | balanced   |
| **Technical** | web\_search, web\_fetch, read, write, exec, edit | balanced   | reactive   | thorough   |
| **Custom**    | you choose                                       | you choose | you choose | you choose |

## Personality settings

Each agent has three personality axes:

| Axis           | Options                         | Description                                 |
| -------------- | ------------------------------- | ------------------------------------------- |
| **Tone**       | casual / balanced / formal      | How the agent sounds                        |
| **Initiative** | reactive / balanced / proactive | How much the agent does without being asked |
| **Detail**     | brief / balanced / thorough     | Response length and depth                   |

## Model selection

Each agent can use a different model:

* **Default** — uses the engine's default model
* **Specific model** — pick from the well-known model catalog or type any model name

Well-known models include:

* **Gemini**: gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash
* **Anthropic**: claude-sonnet-4, claude-haiku-4, claude-opus-4
* **OpenAI**: gpt-4o, gpt-4o-mini, o1, o3-mini

## Skills

Toggle which tools an agent can use:

`web_search` · `web_fetch` · `browser` · `read` · `write` · `exec` · `image` · `memory_store` · `cron` · `message`

See the [Skills guide](/skills) for the full skill vault.

## Soul files

Every agent gets three markdown files that define its identity:

| File            | Purpose                                           |
| --------------- | ------------------------------------------------- |
| **IDENTITY.md** | Name, emoji, vibe, avatar description             |
| **SOUL.md**     | Personality, communication style, boundaries      |
| **USER.md**     | Who the user is, preferences, how to address them |

Additional standard files:

* **AGENTS.md** — Operating rules, priorities, memory usage
* **TOOLS.md** — Notes about local tools and conventions

Edit these in the agent detail view. Changes take effect on the next message.

### Soul file auto-seeding

When a new agent is created, Pawz automatically seeds its soul files so the agent knows who it is from the very first conversation. The seeding process only writes files that **don't already exist**, so your edits are never overwritten.

The auto-seeded files are:

| File            | Seeded content                                                                                                  |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| **IDENTITY.md** | Agent name, ID, role/bio, specialty (from template), personality axes, boundaries, and any custom system prompt |
| **SOUL.md**     | Starter template prompting the agent to develop its own voice using `soul_write`                                |
| **USER.md**     | Starter template prompting the agent to record user preferences via `soul_write`                                |

:::tip
Soul files are stored in the `agent_files` database table, keyed by `(agent_id, file_name)`. Each agent can have any number of additional files beyond the three defaults — agents can create their own files using the `soul_write` tool during conversation.
:::

For agents created by the orchestrator (backend agents), soul files are seeded automatically on the next app load. The `IDENTITY.md` file includes the agent's assigned role and specialty from the project.

## Backend agents

In addition to agents you create manually (stored in `localStorage`), Pawz supports **backend agents** created programmatically by the orchestrator when it plans a project.

### Storage schema

Backend agents live in the `project_agents` SQLite table:

| Column          | Type | Description                                         |
| --------------- | ---- | --------------------------------------------------- |
| `project_id`    | TEXT | The project this agent belongs to                   |
| `agent_id`      | TEXT | Unique agent identifier                             |
| `role`          | TEXT | Agent's role in the project (e.g. `worker`, `boss`) |
| `specialty`     | TEXT | What this agent is good at (see below)              |
| `status`        | TEXT | Current status (`idle`, `busy`, etc.)               |
| `current_task`  | TEXT | The task the agent is currently working on          |
| `model`         | TEXT | Override model for this agent (optional)            |
| `system_prompt` | TEXT | Custom system prompt (optional)                     |
| `capabilities`  | TEXT | Comma-separated list of tool capabilities           |

### Specialties

When the orchestrator creates agents for a project, it assigns each one a specialty:

| Specialty    | Description                         |
| ------------ | ----------------------------------- |
| `coder`      | Writing and editing code            |
| `writer`     | Prose, documentation, copy          |
| `analyst`    | Data analysis and interpretation    |
| `researcher` | Information gathering and synthesis |
| `designer`   | UI/UX and visual design             |
| `tester`     | Testing and quality assurance       |
| `reviewer`   | Code review and feedback            |
| `planner`    | Project planning and coordination   |
| *(custom)*   | Any freeform specialty string       |

:::info
Backend agents appear on the Agents grid with an **"AI-Created"** badge. They are merged into the local agent list on load and receive unique sprite avatars automatically. Their names are derived from the `agent_id` with hyphens replaced by spaces and title-cased.
:::

## Agent-scoped history

When multiple agents share a session (e.g., during orchestration or inter-agent delegation), each agent only sees messages relevant to its own context. Cross-agent tool results from `agent_send_message` and `agent_read_messages` are filtered out for non-default agents.

This prevents context pollution — one agent's delegation results won't confuse another agent's conversation flow. The orchestrator boss agent sees all messages (unfiltered) to maintain full situational awareness.

## Agent policies

Agent policies control **which tools** an agent is allowed to use. This lets you create restricted agents that can only read files, or fully-empowered agents that can execute shell commands.

### Policy modes

| Mode             | Behaviour                                                |
| ---------------- | -------------------------------------------------------- |
| **Allowlist**    | Only explicitly listed tools can be used (strictest)     |
| **Denylist**     | All tools are available *except* those explicitly denied |
| **Unrestricted** | No restrictions — all tools allowed (default)            |

### Tool classifications

Pawz classifies built-in tools into two groups:

**Safe tools** (read-only, low risk):

```
read_file, list_directory, web_search, web_read,
memory_search, soul_read, soul_list, self_info, fetch
```

**High-risk tools** (modify system or send data externally):

```
exec, write_file, delete_file, append_file,
email_send, webhook_send, rest_api_call, slack_send,
github_api, image_generate, soul_write, update_profile,
create_agent, create_task, manage_task
```

### Policy presets

Four presets are available for quick setup:

| Preset           | Mode           | Description                                                                                                                  |
| ---------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Unrestricted** | `unrestricted` | Full access to all tools (default)                                                                                           |
| **Standard**     | `denylist`     | All tools available, but high-risk tools require human-in-the-loop approval                                                  |
| **Read-Only**    | `allowlist`    | Only safe read/search tools — no modifications                                                                               |
| **Sandbox**      | `allowlist`    | Web search and memory only — no file or exec access (`web_search`, `web_read`, `memory_store`, `memory_search`, `self_info`) |

### Additional policy options

| Setting                      | Description                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------ |
| `requireApprovalForUnlisted` | In allowlist mode, tools not in the list still work but require human approval |
| `alwaysRequireApproval`      | List of tools that *always* need approval regardless of mode                   |
| `maxToolCallsPerTurn`        | Limit the number of tool calls an agent can make in a single turn              |

:::caution
Policies are stored per-agent in `localStorage` under the `paw_agent_tool_policies` key. Clearing browser storage resets all policies to the default (unrestricted).
:::

## Avatar system

Pawz ships with **50 pixel-art avatar sprites** in a 1980s Japanese style. The sprites are 96×96 PNG files located at `src/assets/avatars/1.png` through `src/assets/avatars/50.png`.

* A random avatar (1–50) is assigned at agent creation
* The avatar is stored as a numeric string (e.g. `"5"`) in the agent's `avatar` field
* You can change an agent's avatar at any time in the edit view
* Legacy emoji avatars are automatically migrated to sprite avatars on load
* Backend agents get specialty-based avatar assignments: coder → `10`, researcher → `15`, designer → `20`, communicator → `25`, security → `30`, general → `35`, writer → `40`, analyst → `45`

:::tip
The default Pawz agent always uses avatar `5`. If you want to identify agents by specialty at a glance, backend agents are assigned themed sprite numbers based on their role.
:::

## Agent dock

The dock is a floating tray at the bottom-right of the screen:

* Shows all your agents as circular avatars
* Click an avatar to open a **mini-chat** popup
* Unread badge shows new messages
* Collapse/expand with the toggle button
* Tooltips show agent name on hover

## Mini-chat

Each agent has a Messenger-style chat window:

* Opens as a popup from the dock
* Real-time streaming responses
* Full tool execution with approval flow
* Independent session per agent
* Drag to reposition

## System prompt

For advanced users: override the agent's system prompt entirely. This replaces all auto-generated instructions. Use this when you need full control.

## Boundaries

Add custom rules the agent must follow, like:

* "Never share API keys"
* "Always ask before deleting files"
* "Keep responses under 200 words"