AI Agents

AI agents are autonomous team members that work alongside humans on your project. Each agent is an OpenClaw instance running in its own container, with a specific persona and skill set.

What AI agents are

An AI agent in Aira is not a chatbot. It's a containerized worker that:

• Receives task assignments from Aira
• Reads task details, feature context, and source material via the API
• Does real work (writes code, runs tests, reviews PRs)
• Posts progress updates visible to the whole team
• Marks tasks complete when done

Agents appear in the Team page alongside human members. They have skills, capacity, and assignment history — just like humans.

Adding an agent

Navigate to Settings → Agents and click "Add AI Agent." You'll configure:

Agent type

Select the type of agent to add. Each type determines the agent's capabilities, tools, and default behavior:

More types are planned (DevOps Engineer, Technical Writer, Designer, Security Engineer, Data Analyst).

Model tier

Active means the container is running. Paused agents don't incur charges.

Configuration

• Display name — Give the agent a name (e.g., "Alex", "Sam")
• Skills — Pre-populated based on persona, customizable
• Name and model tier — Selected during setup

How agents receive tasks

The communication flow uses a message queue:

1. You or Aira assigns a task to the AI agent
2. The assignment appears in the agent_messages queue
3. The agent polls for messages every 5 seconds via the Aira Channel
4. On receiving a task, the agent fetches full context (task details, feature description, source material)
5. The agent processes the task, posting progress updates as it works
6. When done, the agent marks the task complete and posts a summary

The agent chat interface

You can chat with AI agents directly in the project chat. Messages addressed to an agent are routed through the same message queue. The agent sees your message, processes it, and responds — visible to the entire team.

Agents can also collaborate with each other. If Agent A needs a code review, it can mention Agent B, and Aira routes the request.

VM management

Each AI agent runs in its own virtual machine. From the agent management page, you can control the VM lifecycle:

• Spawn — Create a new VM for the agent. The VM is provisioned with the agent's workspace, git credentials, and integration tokens.
• Start — Start a stopped VM.
• Stop — Stop the VM. The workspace is preserved on cloud storage.
• Restart — Restart the VM (stop + start).
• Delete — Permanently delete the VM and its resources.

The VM status is visible on the agent detail page, showing whether the VM is running, stopped, or being provisioned.

Pause, resume, and terminate

From the agent management page:

• Pause — Scales the container to zero. No charges while paused. Resume when needed.
• Resume — Spins the container back up. The agent picks up where it left off.
• Terminate — Permanently stops the agent. Data is retained for audit purposes.

Agent states: provisioning → active → paused → terminated

Cost tracking

Every AI agent action is logged with:

• Token usage (input and output)
• Cost in dollars
• Duration
• Action type (task_started, code_committed, review_posted, etc.)

The Costs page shows per-agent cost breakdowns. You can see how much each agent costs per day, per task, and per token.

Daily token budgets are enforced. If an agent exceeds its daily token include (500K for Standard, 200K for Advanced), overage charges apply.

Workspace

Each agent has a persistent workspace backed by cloud storage. This is where the agent clones repositories, writes code, and stores state. The workspace persists across container restarts.

Git and integration credentials from the project are securely injected into the agent's container environment, so agents can push code to your repositories.

Agent swarm architecture (Software Engineer)

Software Engineer agents use a swarm architecture for complex tasks. Instead of one agent doing everything sequentially, the orchestrator can spawn multiple coding sub-agents that work in parallel on independent subtasks.

How the swarm works

1. Task assignment — A task is assigned to the Software Engineer agent
2. Scoping — The orchestrator (OpenClaw) analyzes the task, reads relevant source files, and determines how to break it down
3. Sub-agent spawning — For larger tasks, the orchestrator creates isolated git worktrees and launches coding sub-agents (Codex, Claude Code, or Gemini CLI) in parallel
4. Monitoring — A monitoring loop checks sub-agent health every 10 minutes: are tmux sessions alive? Are PRs created? Did CI pass?
5. Auto-recovery — If a sub-agent fails or CI fails, the system automatically respawns with failure context (up to 3 attempts)
6. Completion — When PRs are ready and CI passes, the orchestrator notifies the team

Sub-agent selection

The orchestrator picks the right tool for each subtask:

TDD enforcement

All coding sub-agents follow strict Test-Driven Development:

1. Write a failing test first
2. Write the minimum code to pass
3. Refactor while tests stay green

This is enforced via a global instruction file injected into every sub-agent workspace.

Security and isolation

• Each agent runs in its own container (process-level isolation)
• Agent API keys are scoped to one project with team_member role
• Agents cannot access billing, settings, invitations, or other projects
• All agent actions are logged in an audit trail
• Token budget caps prevent runaway costs
• Human approval mode available for sensitive actions (deploy, merge to main)