Xera Docs
System Deep Dive
A practical look at how Xera's agents, threads, runs, workers, and queues work together
How Xera's Agent System Works
Xera is built around an event-driven architecture where user actions create threads and runs, which are executed by background workers connected to a queue (Redis). The UI streams token-by-token output as the agent reasons, calls tools, and produces artifacts.
Core Concepts
- Agent: A configured worker with tools, constraints, memory, and policies.
- Thread: A conversation timeline tying messages, files, and tool results.
- Run: A single execution pass of an agent in a thread with a specific goal.
- Tool Calls: Secure, scoped actions (web, files, email, APIs) invoked by the agent.
- Artifacts: Outputs like docs, spreadsheets, and exported reports.
Agent Example
“SEO Analyst” using Web Browse + Sheets, memory on, approval before publishing.
Thread Example
Messages: kickoff → research results → edits → final approval; files attached: sitemap.xlsx
Run Example
Goal: “Generate keywords for 10 pages” • Steps: crawl → cluster → write → review
Tool Calls Example
Browse → extract → write to Sheets; all calls logged with params and outputs.
Artifacts Example
Generated “keywords.csv” and “strategy.md”, both linked from the run trace.
Execution Flow
- User submits a message or workflow trigger starts a run.
- The backend enqueues a job; a background worker picks it up.
- The worker streams tokens back to the UI and performs tool calls as needed.
- State (messages, tool results, costs) is persisted for observability.
- Completion signals the UI and any webhooks or follow-on automations.
Workers & Queues
- Redis powers pub/sub and job queues for resilient processing.
- Workers handle long-running tasks (multi-step reasoning, scraping, file ops).
- Built-in backoff, retries, and idempotency guards reduce flaky failures.
- Scale horizontally by running more worker processes.
Tools, Sandboxing, and Safety
- Tools are permissioned and parameterized; calls are logged and auditable.
- Daytona provides isolated sandboxes for code execution when required.
- Rate limits and cost caps protect budgets and external APIs.
- Structured streaming keeps the UI responsive and transparent.
Architecture Diagram
High-level flow of a run through Xera's system.
Behind the Scenes
These are the building blocks Xera uses under the hood. You don’t need to set them up—this is here to explain how the system works.
Stores users, conversations, agent configs, and access control.
Moves work from the API to background workers reliably (pub/sub + jobs).
Execute runs, stream tokens, and call tools with backoff and retries.
Isolated environments for code execution when an agent needs it.
Reasoning and generation models used by agents during runs.
Find and extract information from the web for research tasks.
Scaling Workers
For heavier workloads, scale background workers horizontally. Each process pulls jobs from Redis and runs independently.
- Set sensible timeouts for long-running tools.
- Use rate limiting to protect third-party APIs.
- Monitor Redis memory and connection counts under sustained load.
- Forward structured logs to your observability stack.
TL;DR
Submit → API enqueues → Workers execute → Tools run safely → UI streams results.
That’s the loop powering agents, with Redis for reliability and Supabase for state.