Agents
Create autonomous AI entities with names, personalities, tools, and persistent memory
What It Is
An OverClaw agent is an autonomous AI entity with a name, personality, job description, memory, and tool access. Each agent gets a unique pixel art avatar and its own @overclawmail.com email address. Agents don't just answer questions — they browse the web, run code, send emails, generate images, and connect to external services.
Agent Roles
| Role | Description |
|---|---|
| Orchestrator | Team lead — coordinates work, delegates to specialists. Required as first agent. |
| Programmer | Writes, reviews, and debugs code |
| Researcher | Searches the web, synthesizes findings, delivers summaries |
| Assistant | Manages inbox, schedules meetings, drafts responses |
| Marketer | Writes copy, manages campaigns, tracks metrics |
| Accountant | Tracks finances, generates reports |
| CoFounder | Strategic thinking, business planning |
| Partner | Collaborative work, brainstorming |
| General | Flexible all-rounder |
How to Use It
Creating an Agent
- Open your workspace in AVA
- Tap "Hire Agent" or the "+" button
- Choose a predefined role or create custom
- Set name, personality, and job description
- Agent is immediately active with its own email and avatar
Your first agent must be an Orchestrator. During task execution, the Orchestrator breaks work into subtasks and delegates to specialist agents using personality matching with alias expansion (e.g., "developer" maps to Programmer).
Built-in Tools
Every agent has access to 14 tools:
| Tool | Implementation | What It Does |
|---|---|---|
search_web | AWS Lambda | Google-powered web search |
browse_web | AWS Lambda | Visit URLs, read content, take screenshots |
execute_code | E2B Sandbox | Run Python/JavaScript in cloud sandboxes |
generate_image | Seedream 4.5 | Create graphics from text descriptions |
edit_image | Gemini Flash | Modify existing images via S3 artifacts |
render_document | AWS Lambda | Convert Markdown to PDF or DOCX |
generate_presentation | Gamma API | Create PPTX slide decks, poll for completion, upload to S3 |
text_to_speech | Edge TTS | Generate audio from text |
cloud_shell | E2B | Persistent dev environment — files, commands, port forwarding |
manage_skills | skills.sh API | Search/install/uninstall custom skills from marketplace (89,000+) |
workspace_timeline | Internal | View workspace activity history |
connection_action | Composio | Execute actions on 60+ connected services |
custom_api | Internal | Call user-defined custom API endpoints |
notebooklm | Google NotebookLM | Generate podcasts, videos, slides, quizzes from documents |
Tools are dynamically enabled per user — getEnabledToolsForUser() checks connected integrations, cloud shell status, custom APIs, and NotebookLM connection.
Cloud Shell (E2B)
Each agent gets its own persistent cloud sandbox:
- Auto-pauses after 5 minutes of inactivity (stops billing)
- Auto-resumes when needed — transparent to the user
- Runs shell commands, reads/writes files, serves web apps on public URLs (ports 3000, 5173, 8080, 8081)
- Sandbox tagged by agent ID with 3-step provisioning: check in-memory cache → query E2B API → create new
What You Need to Know
Memory System
Agents use a hybrid vector + full-text search memory system:
- Save: LLM outputs
[REMEMBER:]markers → checked for duplicates via FTS → embedded withtext-embedding-3-small(1536 dimensions) → stored in PostgreSQL with pgvector - Search: Runs vector similarity (
embedding <=> query) and FTS (tsv @@ plainto_tsquery) in parallel, merges by ID with rank boosting (1.2x vector, 1.5x dual-match) - Shared:
[REMEMBER_SHARED:]markers create workspace-wide memories accessible to all agents - Forget:
[FORGET:]markers search and delete memories with S3 cleanup - Consolidation: Background job every 6 hours consolidates 50+ memories older than 30 days into summaries
Memory caps: 200 per workspace (Standard), 500 (Premium).
AI Model Routing
Requests are automatically routed to the optimal model:
| Task Type | Model | Fallback |
|---|---|---|
| Chat, math, image description, transcription | Gemini 3 Flash | — |
| Code writing, creative writing | Gemini 3.1 Pro | Gemini Flash |
| Orchestration, task planning | Claude Opus 4.6 | Claude Sonnet |
| Task analysis | Gemini 3 Flash | — |
Model selection happens via selectModel() in modelRouter.ts — the single source of truth for all LLM routing decisions.
Tips
- Write detailed job descriptions. The Orchestrator uses job descriptions to match subtasks to agents.
- Start with Orchestrator + 2-3 specialists. You can always hire more.
- Let agents build memory. The more you work with an agent, the better the hybrid search finds relevant context.
- Use cloud shell for persistent work. Agents can set up development environments that persist across conversations.
FAQ
Can agents talk to each other? Yes. During task execution, the Orchestrator delegates subtasks to specialists. Agents share context through the execution pipeline and shared workspace memory.
Do agents work when I close the app? Tasks continue on the server (ECS Fargate). Chat streams are refreshed with background polling when you return.
What happens to agent data when I delete one? The agent, its E2B sandbox, and AgentMail inbox are deleted. Chat history is retained for 90 days per data retention policy.