agent-augury

Local multi-agent collaboration — shared threads, roles, and human-in-the-loop.

Model-agnostic runtime for teams of LLM agents that keep working while teammate messages arrive.

What it is

agent-augury is a local Python runtime for running several LLM agents as a team:

• shared conversation threads with @mentions and broadcast
• non-blocking delivery — agents keep working; messages land at the next step()
• assignable roles, optional P1–P5 collaboration protocol
• you as a first-class participant (ask_user, Ink UI, Discord/Slack mirrors)
• model-agnostic backends (OpenAI-compatible, Nous API key / OAuth)

Install it, configure agents in YAML (or the wizard), and run a session from the terminal.

                         You (Ink / Discord / …)
                                │
                          Session + Gateway
                                │
               ┌────────────────┼────────────────┐
               ▼                ▼                ▼
           Agent A          Agent B          Agent N
           (any model)      (any model)      (any model)
               │                │                │
               └────────────────┼────────────────┘
                                ▼
                       Message Server (SSOT)

How teammates communicate

Agents talk through three primitives:

Messages are pushed into each target's inbox. On the next step(), the runtime drains that inbox into the agent's context — no blocking “wait for reply” loop.

In the Ink Surface you can direct a mid-session note with @agent-id … (omit @ to broadcast).

Roles

Give each agent a persona from config:

roles:
  orchestrator:
    prompt: |
      You are the orchestrator. Decompose work, coordinate, and integrate results.
  architect:
    prompt: |
      You are the architect. Design structure, tech stack, and trade-offs.

agents:
  - id: agent-1
    role: orchestrator
    backend: { ... }

• role: <name> uses a preset; role_custom: "..." is inline.
• Agent ids must be unique (case-insensitive). The id human is reserved.

Human-in-the-loop

You are a first-class participant:

• Agents can call ask_user(question, options?) mid-session
• Your reply (and free-form @agent-id notes) use the same inbox path as agent messages
• On a TTY with Node.js, Ink is the interactive Surface (always-on input)

agent-augury --config session.yaml

Optional Discord bots / webhook mirrors and Slack webhooks are observe (or opt-in inbound) surfaces — protocol state stays in the message server.

Collaboration protocol (optional)

A five-phase flow is available when you enable protocol: in config:

P1 EXPLORE → P2 SPLIT → P3 EXECUTE → P4 REVIEW → P5 SUBMIT

Gates require explicit group approval before advancing. Use it when you want structured team work; omit it for free-form multi-agent sessions.

Model agnostic

Backends share one interface. Mix providers per agent:

• OpenAI-compatible APIs (including OpenRouter)
• Nous Portal (API key)
• Nous Portal (OAuth device code)
• type: fake only with --demo (tests / offline examples)

Secrets stay in environment variables; YAML stores env names only.

Quick start

Install

pip install agent-augury

Ink Surface (required for the interactive TUI):

1. Install Node.js >= 22 so npm is on your PATH (nodejs.org).
2. Run agent-augury — the wheel bundles fronts/ink sources; on first launch they are copied to a user cache and npm install runs there.
3. Optional overrides:
   • AUGURY_INK_DIR — use a specific Ink front directory (e.g. a git checkout of fronts/ink)
   • AUGURY_PROJECT_ROOT — repo root when developing from a clone
   • AUGURY_CACHE_DIR — base directory for the Ink cache (default: platform cache)

Developers working from this repository can use an editable install (uv sync / pip install -e .); the checkout’s fronts/ink is picked up automatically.

Wizard

agent-augury

Run a session

agent-augury --config examples/consensus_openai.yaml

Offline / CI-style example (scripted backends):

agent-augury --demo --config examples/demo.yaml

Protocol example:

agent-augury --demo --config examples/p1_to_p5_protocol.yaml

Command-line options

Design principles

1. Keep working while listening — teammate traffic must not force a blocking wait.
2. No single agent is SSOT — the message server owns shared state.
3. Surfaces are views — Discord/Slack/Ink observe or interact; they do not own protocol state.
4. Models are swappable — communication rules live in the runtime, not one vendor SDK.
5. Humans participate — ask, answer, and @mention mid-session without special-casing the protocol.
6. Stay observable — tools, steps, and messages stream on the Wire bus for UIs and mirrors.

See DESIGN.md for implementation history and protocol details.

Attribution

Non-blocking teammate-inbox messaging is related to ideas explored by AgentRadio (Apache-2.0; arXiv:2607.28430). agent-augury is an independent implementation. See NOTICE.

License

Apache-2.0