AI Agent Overview

The AI agent is the most important surface in Swarmz. Every other feature — Cloud, Git sync, deployments — exists so the agent can do its job. This page explains the mental model and the moving parts. Read it before you read anything else in this section.

The mental model

You can think of the agent as a junior engineer who joined your team this morning. It already knows the framework you're using, but it doesn't know your code yet. So before it touches anything, it does what a careful engineer would do.

The streaming loop

Under the hood, your prompt becomes an HTTP POST to the /v1/ai/chat edge function with Accept: text/event-stream. The response is a long-lived SSE stream — the connection stays open while the agent works, and each event is a structured JSON message.

POST /functions/v1/ai-chat-v3
Content-Type: application/json
Accept: text/event-stream

{ "projectId": "...", "message": "add a login form", "viewingPath": "/" }

The events you'll see in the timeline:

The frontend hook useChatStreamV2 parses these events and updates the chat panel, file tree, and preview iframe in real time. If the connection stalls for 180 seconds, a watchdog cancels and shows a retry button.

Multi-model routing

You don't pick the model. The pipeline picks the right one for each phase, optimizing for latency and cost:

Per-stage configuration lives in the model_stage_config table and can be swapped by an admin without redeploying. Most prompts only use Sonnet — the other models kick in for plan mode, scout passes, and compaction.

Knowledge presets and skills

The agent has two ways to load domain context beyond your codebase:

• Knowledge presets are admin-curated topic packs (e.g. Stripe checkout, Supabase auth, shadcn theming). The agent calls knowledge_search and knowledge_get to pull just the relevant snippets. You attach presets per project from the editor's right rail.
• Skills are user-configurable behavior toggles. They modify the system prompt — for example, a pixel-perfect-tailwind skill nudges the agent toward exact spacing values instead of approximations.

Both are loaded once per request and cached for 5 minutes. They never bloat the prompt unless the agent actively pulls them in.

Limits

The agent runs inside hard guardrails so it can't loop forever or burn through your credits:

When a budget is hit, the agent gets a system message — "Context budget reached. Call done immediately." — and wraps up with whatever it's done so far. You'll see a compact_notice event if it had to summarize older turns to keep going.

Credit costs per action

Every prompt deducts credits based on actual token usage rather than a flat per-action fee. Rough action-type ranges:

Deductions drain a 4-pool cascade: daily_bonus → included_credits (your plan) → rollover_credits (prior cycle, expires after rollover window) → topup_credits. See Credits for the full breakdown.

Where to next

• Prompting Tips — how to actually get good output
• Plan Mode — review changes before they happen
• File Operations — every tool the agent can invoke