AgentWeave

What if AI agents worked like a real team — proposing, debating, and refining ideas — instead of each working alone?

Today's AI agents are brilliant but lonely. Each one works in isolation: no colleagues to challenge its assumptions, no second opinion, nobody to ask "wait, did you think about…?" For simple tasks that's fine. For complex decisions — planning, engineering, strategy — a single agent is one-track-minded by design.

AgentWeave is an open-source runtime where multiple AI agents collaborate the way good human teams do:

1. Propose — agents independently draft competing solutions, no groupthink.
2. Critique — a reviewer agent challenges every proposal and finds the holes.
3. Rebut — proposers defend their ideas and address the criticism.
4. Synthesize — a lead agent combines the best of all sides into one decision.
5. Human steer — at key moments, a human steps in to set direction ("prioritize sustainability", "cap the budget"), and the synthesis must honor it.

The result is more robust than any single agent's answer — not because the models are smarter, but because the process is: multiple perspectives, honest debate, human judgment where it matters most.

Status: pre-1.0 developer preview. The collaboration loop above runs today against a deterministic mock provider (see demo/ for the recorded 116-second walkthrough); real-provider and autonomous collaboration work is tracked in the v0.2 roadmap.

---

AgentWeave is an open-source runtime OS for collaborative AI agents. An agent is not an isolated chat session: it is an actor inside a durable, observable, and human-steerable system that can coordinate with other actors and safely resume after interruption.

The runtime owns the workstream, task graph, message delivery, provider session, workspace boundary, evidence, recovery, and approval points. Agents are replaceable workers; the runtime is the product.

This repository is pre-1.0 and currently focused on a single-host, Docker-first MVP for software-development workstreams. It is not production-hardened for untrusted multi-tenant deployment.

Research context and design thesis

AgentWeave is built around a simple thesis: the innovation space of multiple collaborating agents can be larger than a single Agent ↔ Human conversation. The important difference is not merely using more model calls. Different agents can hold different roles, challenge assumptions, propose alternatives, divide the search space, and combine partial solutions before a human reviews the result.

This thesis is informed by research on multi-agent conversation, role-based collaboration, and debate. AutoGen presents flexible applications built from conversable agents, humans, and tools; CAMEL studies role-playing agents that cooperate with less continuous human steering; multi-agent debate reports gains in reasoning and factuality from independent proposals and critique; and MetaGPT shows how role-specialized workflows can structure complex software engineering tasks.

These works do not imply that adding agents automatically improves a system. Naive agent chains can multiply inconsistency and hallucination. AgentWeave's contribution is therefore the runtime around collaboration: durable messages, explicit task ownership, observable state transitions, evidence, recovery, and human approval.

References:

• AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation
• CAMEL: Communicative Agents for “Mind” Exploration of Large Language Model Society
• Improving Factuality and Reasoning in Language Models through Multiagent Debate
• MetaGPT: Meta Programming for A Multi-Agent Collaborative Framework

The core loop is:

goal → decompose → assign or parallelize → execute → communicate → review
     → attach evidence → recover or continue → request human approval

This makes long-running work visible: humans can see what each agent is doing, which task is moving, what messages caused a handoff, and why the system is waiting.

Architecture

The two diagrams below deliberately separate the current, code-backed runtime from the agent-owned collaboration vision. Solid components and arrows in the first diagram describe behavior implemented on main. Dashed components and arrows in the second are planned work, not product claims.

Current runtime architecture

flowchart TB
    Human[Human operator] <--> Dashboard[React Dashboard<br/>operator console]

    subgraph Control[Control Plane — current implementation]
        API[Control API<br/>HTTP · WebSocket · lifecycle]
        Orch[Lifecycle & legacy orchestrator<br/>routing · state transitions · recovery]
        Gate[Structured Result Gate<br/>validate agent result · resolve roles · apply approval rules]
        Projection[Snapshot & runtime projection<br/>durable state + live events]
    end

    subgraph Durable[Durable Backbone — current implementation]
        DB[(PostgreSQL — source of truth<br/>tasks · insights · messages · evidence · sessions · receipts)]
        NATS[(NATS JetStream — durable transport<br/>inboxes · commands · execution events)]
    end

    subgraph Runtime[Execution Plane — one or more Worker processes]
        Worker[Worker Runtime Pool]
        Actor[Dynamic AgentRuntime<br/>one serialized inbox per agent identity]
        Session[Durable provider session<br/>checkpoint · resume · cancellation]
        Adapter[Provider adapter<br/>Mock · Codex App Server · Claude Code]
        Workspace[Workspace & evidence boundary<br/>tests · diffs · artifacts]
        Worker --> Actor --> Session --> Adapter
        Actor --> Workspace
    end

    Dashboard <--> API
    API --> Orch
    API --> Projection
    API <--> DB
    Orch --> DB
    Orch --> NATS
    NATS -->|worker result events| Gate
    Gate -->|atomic task · insight · inbox-message effects| DB
    Gate -->|recipient inbox delivery after commit| NATS
    NATS --> Worker
    Worker -->|normalized execution events| NATS
    DB --> Projection

Loading

PostgreSQL is the source of truth. The Control API writes durable state and then publishes inboxes/events through JetStream; a crash-atomic transactional outbox is not implemented yet.

Agent-owned collaboration vision — planned

Everything dashed in this diagram is planned. The implemented Control API, PostgreSQL, and JetStream boundary remains the validation and durability point even as agents become more self-directed.

flowchart TB
    Human[Human operator] <--> Dashboard[React Dashboard]

    subgraph CurrentBoundary[Current durable boundary — implemented]
        Gate[Control API<br/>validation · policy · durable commit]
        DB[(PostgreSQL<br/>source of truth)]
        NATS[(NATS JetStream<br/>durable inbox transport)]
        Gate <--> DB
        Gate --> NATS
    end

    subgraph PlannedRuntime[Planned: agent-owned collaboration runtime]
        Inbox[Read durable Inbox]
        Context[Build Context Pack<br/>task · evidence · session summary · memory]
        Loop[Plan → Act → Observe]
        Tools[Provider & tools]
        Result[Structured result<br/>insight · task · message · decision]
        Memory[Memory, summaries & compaction]
        Inbox -.-> Context -.-> Loop -.-> Tools -.-> Result
        Loop -.-> Memory
        Memory -.-> Context
    end

    subgraph PlannedHive[Planned: multiple dynamic agent identities]
        PM[PM]
        PE[PE]
        Coder["Coder(s)"]
        QA[QA]
        PM <-. structured messages / shared insights .-> PE
        PM <-.-> Coder
        PE <-.-> QA
        Coder <-.-> QA
    end

    Dashboard <--> Gate
    NATS -. planned autonomous inbox consumption .-> Inbox
    Result -. validated before effects .-> Gate
    Loop -. one loop per identity .-> PM
    Loop -.-> PE
    Loop -.-> Coder
    Loop -.-> QA

Loading

Control Plane

The Control API is the provider-neutral coordination boundary. It exposes HTTP and WebSocket APIs for the dashboard, owns workstream lifecycle commands, creates and updates tasks, applies policy and approval rules, and runs the Orchestrator state machine.

The Orchestrator handles routing, state transitions, retries, recovery, and human escalation. It can coordinate sequential work as well as independent or parallel tasks; a task does not have to be a strict child of another task.

Durable Backbone

PostgreSQL is the source of truth for workstreams, agents, tasks, messages, inboxes, sessions, leases, and evidence. NATS JetStream transports commands and events between the Control Plane and workers with durable consumers, acknowledgements, retries, and dead-letter handling.

The dashboard is a read-oriented operator console. Its task board, agent execution cards, live message bus, summaries, and activity views are projected from durable state and live events, so a refresh does not erase the history.

Execution Plane

Workers register, send heartbeats, acquire task leases, consume agent inboxes, run provider sessions, and publish normalized execution events. Each runtime actor has its own role, status, current task, session, usage, and auditable output.

The provider adapter boundary supports Mock, Codex App Server, Claude Code, and future providers behind one contract for streaming, cancellation, resume, failure classification, checkpoints, and usage. Workspace access is explicit and bounded; tests, diffs, tool output, and artifacts are persisted as evidence instead of remaining hidden in a transcript.

The renderable sources are architecture.mmd (current) and architecture-vision.mmd (planned vision).

Runtime concepts

• Workstream — a durable long-running objective and its lifecycle.
• Task — an actionable unit with an owner, acceptance criteria, dependencies, relationships, status, and evidence. Tasks may be sequential, parallel, or independent.
• Agent actor — a runtime identity such as PM, PE, Coder, or QA. A role is an execution responsibility, not a separate product.
• Message bus — durable human ↔ agent and agent ↔ agent communication with correlation and causation IDs.
• Session — provider-specific state that can be leased, checkpointed, resumed, cancelled, and safely retried.
• Human boundary — explicit pause, resume, approval, rejection, and escalation points. Autonomy remains legible and controllable.

Technology stack

• TypeScript monorepo managed by pnpm and Turborepo
• React 19, Mantine, and React Flow for the operator dashboard
• Fastify for the Control API
• PostgreSQL for durable state and session recovery
• NATS JetStream for commands, events, inboxes, ACKs, retries, and DLQ flows
• Docker Compose for the local runtime
• Vitest, Playwright, and TypeScript checks for validation
• Prometheus, Loki, Promtail, and Grafana for local observability

Capability matrix

AgentWeave is a developer preview. The table below separates behavior that is available on main from work that is intentionally still in progress.

Capability	Status	Current boundary
Durable Workstreams, Tasks, Messages, evidence, and provider sessions in PostgreSQL	Implemented	Designed for the trusted, single-host Docker deployment
Per-Workstream event sequence, reconnect cursor, and persisted Dashboard projections	Implemented	Replays committed history; full crash-atomic publication is not yet guaranteed
Deterministic Mock-provider operator journey	Implemented	Playwright covers create, start, activity, Human approval, and persisted completion
Mock, Codex App Server, and Claude Code provider adapters	Implemented	Mock is the supported deterministic path; real providers require local credentials and configuration
Durable agent inboxes and structured Human ↔ Agent / Agent ↔ Agent messages	Partial	Transport and contracts exist; agent-owned collaboration policy is still evolving
Insight and collaboration-round contracts, persistence, and read projections	Partial	Durable data model exists; automatic proposal/critique/synthesis rounds are planned
Worker heartbeats, task leases, retries, and dead-letter handling	Partial	Basic runtime signals exist; dependency-aware scheduling and cross-Worker lease recovery are planned
Transactional state change + event outbox	Planned	A crash between database commit and event publication can still require operator diagnosis
Production security and untrusted multi-tenancy	Not supported	No built-in authentication/authorization boundary; deploy only on a trusted local network

“Implemented” describes code exercised on main; it is not a production support guarantee. See the open v0.2 roadmap for the remaining reliability and collaboration work.

Structured agent results

Workers forward validated AgentTurnResult values to the Control API. An agent can propose insights, assign tasks, and address another role directly; the runtime resolves role names and turn-local IDs rather than trusting model-supplied agent or workstream identities. Insight references must resolve within the same workstream, and cited evidence must belong to the executing task.

To dispatch a newly proposed task, include a message whose taskId matches that task's local id and whose recipientRole matches its ownerRole. Creating a task alone does not schedule it. Results may also request Human input or propose completion; neither bypasses Human approval. Summary-only results retain the legacy orchestration path, while malformed declared JSON is rejected.

Tasks, insights, durable inbox messages, source-task status, and a retry receipt are committed in one PostgreSQL transaction. Reapplying the same turn does not duplicate these records, and conflicting reuse of a turn ID is rejected. NATS publication follows that transaction: this is not a crash-atomic outbox or a complete autonomous collaboration policy yet. The deterministic Mock demo exercises a structured PM → PE → Backend → QA → PM handoff and persists a proposal.

CI runs PostgreSQL-backed retry/rollback tests and a Playwright journey that verifies the proposal remains after reload. Run the database checks against a disposable database with STRUCTURED_TURN_TEST_DATABASE_URL set and pnpm --filter @agentweave/control-api exec vitest run tests/structured-turn-postgres.test.ts.

Day 1 scope

• Create one durable workstream.
• Register PM, PE, Coder, and QA sessions.
• Route typed human and agent messages through NATS JetStream.
• Persist workstream state and read models in PostgreSQL.
• Display agents, chat, activity, and controls in a React dashboard.
• Run a fixed end-to-end workflow with pause, resume, human review, and completion.

Repository layout

apps/control-api  HTTP/WebSocket control plane
apps/dashboard    React operator console
apps/worker       Local multi-role worker runtime
packages/protocol Provider-neutral event and command schemas
packages/domain   Workstream state machine and domain rules
docs              Product specification and implementation backlog

Quick start: reliable local demo

The default provider is deterministic mock, so anyone with Docker can see a workstream run without provider credentials or access to a real repository.

corepack enable
pnpm install
cp .env.example .env
make demo

Open the Dashboard at http://localhost:5173 and select the created demo workstream from the Workstreams menu. make demo is safe to run again: it creates another disposable demo workstream; it never deletes existing work.

You can also create the demo directly in the Dashboard from New Workstream by choosing Create demo workstream. The mock demo visibly moves through PM → PE → Coder → QA and then stops at Human review, with no provider credentials or real project workspace required.

Dashboard: http://localhost:5173 Control API: http://localhost:3000/health NATS monitoring: http://localhost:8222

For a prerequisite check, run make doctor. For the full development and configuration guide, see docs/DEVELOPMENT.md and docs/CONFIGURATION.md.

To remove only your local Docker state and begin from an empty database, run make fresh CONFIRM=YES. This intentionally deletes local database, NATS, and observability volumes; it does not delete the mounted workspace directory.

Run with Codex

Codex is an opt-in local preview, not required for the quick start. The bridge executes Codex on your host while the Worker stays in Docker.

1. Set AGENTWEAVE_PROVIDER=codex in .env.
2. Set both AGENTWEAVE_HOST_WORKSPACE and CODEX_HOST_WORKSPACE_ROOT to the same narrow directory that you explicitly allow AgentWeave to access.
3. Generate a private CODEX_BRIDGE_TOKEN and place it only in .env.
4. Start the bridge in a separate terminal with make bridge, then run make demo-codex in another terminal. This is the one-command way to start the stack with the real Codex provider and create a demo workstream. To start the Codex-backed stack without creating a demo, run make up instead.

To verify the authenticated provider boundary without changing files, run the documented read-only smoke turn from another terminal:

CODEX_SMOKE_WORKSPACE=/absolute/path/inside/the/allowed/root pnpm test:smoke:codex

make bridge loads .env before starting, so the host bridge uses the same workspace mapping as Docker.

The bridge defaults to localhost when no token is set. Do not mount a home directory, expose the bridge publicly, or put provider credentials in task messages, logs, screenshots, or Git.

Release status

AgentWeave is pre-1.0 / developer preview. It is intended for trusted, single-host experimentation. It is not production-hardened or suitable for untrusted multi-tenant deployment.

Developer-preview release checklist

Before tagging or publishing a developer-preview build:

• Start from a clean clone with Node.js 22+, pnpm 11.2.2, and a running Docker daemon.
• Run cp .env.example .env, corepack enable, pnpm install, and make demo; confirm the Dashboard reaches Human review without manual database changes.
• Run pnpm run typecheck, pnpm run test, and pnpm run build.
• Run the deterministic browser journey with pnpm test:e2e; it must not require provider credentials or paid tokens.
• Confirm the repository's CI workflow passes its quality, docker, and e2e jobs for the release commit.
• Review SECURITY.md, keep PostgreSQL, NATS, observability, and the Codex bridge private, and verify no credential or broad host workspace mount is included.
• Record known limitations from the capability matrix in the release notes; do not claim transactional crash recovery, untrusted multi-tenancy, or autonomous collaboration until their roadmap issues are complete.

Community and security

• Contributing
• Security policy
• Code of Conduct
• Changelog

AgentWeave is released under the Apache License 2.0.