InterAgents

InterAgents is a deterministic, traceable message-passing runtime for coordinating role-specific LLM agents under explicit policy and trace constraints.

It is not a chatbot pipeline. The core asset is the governed runtime loop:

MessageEnvelope
-> Orchestrator
-> Agent.handle
-> MessageEnvelope
-> RunState
-> Policy
-> Trace

Agents provide reasoning roles around that runtime. Policies constrain what the loop may do. Tools execute deterministic work. Traces make each run inspectable.

Project Status

InterAgents has reached closure for its current intended scope: a deterministic, traceable local runtime core with a stable canonical workflow for demo, evaluation, and trace inspection. Future work can extend the project, but the current closure boundary is the governed runtime spine described below.

The canonical demo exercises the current runtime spine:

• governed runtime execution
• structured supervisor routing
• research, critique, and writing roles
• deterministic policy guardrails
• deterministic tool execution
• evidence routing
• closed-loop retry from critique back to research
• explicit control-plane stopping
• NDJSON execution traces

The public command-line surface is the preferred way to run the current workflows:

interagents version
interagents demo unit5
interagents eval
interagents trace summary runs/<run_id>.jsonl

The deeper refactor roadmap lives in docs/refactor_phases.md. Phase history and closeout notes are linked from AI_native_builder_journal.md.

Quick Start

From the project root, install the package in editable mode:

python -m pip install -e .

For local test work, install the development extra:

python -m pip install -e ".[dev]"

For live OpenAI smoke tests, install the OpenAI extra and provide credentials:

python -m pip install -e ".[openai]"

Run the canonical demo:

interagents demo unit5

Expected stop reason:

UNIT5_REAL_SUPERVISOR_RETRY_LOOP_COMPLETE

Run the deterministic evaluation harness:

interagents eval

Inspect a trace summary:

interagents trace summary runs/<run_id>.jsonl

The same workflows are also available without installing the console script:

python -m interagents.cli version
python -m interagents.cli demo unit5
python -m interagents.cli eval
python -m interagents.cli trace summary runs/<run_id>.jsonl

The canonical demo can also be run through its module entry point:

python -m interagents.tuning.golden_path_unit5

Canonical Runtime Map

The current governed runtime path is intentionally small:

interagents.core.runner_v1.run_loop_v1
-> interagents.core.orchestrator.Orchestrator
-> interagents.core.agents.*
-> interagents.core.state.RunState
-> interagents.core.policies
-> interagents.services.trace.TraceLogger

Version suffixes remain on public contracts where they mark stable contract generations, such as RunResultV1, StopPolicyV1, and SupervisorDecisionV1. Compatibility shims preserve older imports where needed; historical and experimental paths are documented in the phase notes rather than treated as the main product surface.

Architectural Thesis

InterAgents treats LLMs as controlled components inside a governed runtime.

The framework is designed around:

• deterministic orchestration where possible
• typed message boundaries
• role-specific agent contracts
• policy-constrained routing
• evidence-grounded outputs
• trace-first debugging
• deterministic tests before real LLM integration

The agents are important, but they are extensions around the runtime. The runtime is the product center.

Current Runtime Flow

task.request
   |
   v
SupervisorAgent
   |
   v
ResearchAgent
   |
   v
evidence.packet
   |
   v
CriticAgent
   |\
   | \ NEEDS_MORE_EVIDENCE
   |  v
   |  Supervisor retry
   |  |
   |  v
   |  ResearchAgent
   |
   v PASS
WriterAgent
   |
   v
draft
   |
   v
STOP

Core Invariants

These are the architectural rules the refactor should preserve and sharpen.

Single Canonical Loop

Canonical execution flows through:

run_loop_v1(...)

There should be no hidden agent-to-agent loops.

Envelope-Based Communication

Agents communicate through:

MessageEnvelope

No direct agent-to-agent calls should bypass the orchestrator.

Run State Is Runtime State

RunState tracks what happened in one run. It is not long-term memory.

Runtime state should be owned by the loop, not cached independently inside agents.

Policies Are Deterministic

LLMs may propose routes or structured decisions. Deterministic policies decide whether those proposals are legal.

Traces Are First-Class

Each run writes an NDJSON trace file:

runs/<run_id>.jsonl

The trace is the debugging artifact for agent steps, LLM calls, tool calls, decisions, and stop behavior.

Agent Roles

SupervisorAgent

The route proposer and workflow coordinator.

• routes work between agents
• uses structured LLM decisions
• must not draft
• should not own durable run state
• should become thinner during the refactor

ResearchAgent

The evidence gatherer.

• accepts task.request
• executes deterministic tools
• emits evidence.packet
• does not draw conclusions

CriticAgent

The evidence evaluator.

• accepts evidence.packet
• emits critique
• can return PASS, FAIL, or NEEDS_MORE_EVIDENCE
• produces structured followups

WriterAgent

The evidence-bound drafter.

• accepts evidence.packet
• emits draft
• cites only provided evidence source IDs
• refuses when evidence is insufficient

Command-Line Interface

The CLI is a small wrapper around the canonical local workflows. It does not replace module entry points, add a server, or change runtime semantics.

interagents version
interagents demo unit5
interagents eval
interagents trace summary runs/<run_id>.jsonl

interagents demo unit5 runs the canonical demo and reports the governed stop reason. interagents eval runs the deterministic evaluation harness offline. interagents trace summary <path> prints compact NDJSON trace metadata instead of dumping the full trace file.

Exit code 0 means the command completed successfully. Non-zero exit codes mean invalid input, unreadable trace input, or a failed deterministic run.

Tests

Run the suite:

pytest -q

After the Phase 15a closeout hygiene pass, the deterministic suite is green locally:

203 passed, 3 skipped

Live OpenAI smoke tests are opt-in so contract tests stay deterministic offline. Set OPENAI_LIVE_TESTS=1 and OPENAI_API_KEY before running:

pytest -q tests/test_phase13_real_llm_confidence.py tests/test_openai_transport_smoke.py tests/test_openai_transport_alternative.py

Project Structure

interagents/
  core/         orchestration, messages, state, agents, policies
  corpus/       corpus indexing and deterministic search
  services/     trace, cost, retry, structured errors
  tools/        deterministic tool layer
  transports/   external LLM transport adapters
  tuning/       golden-path demos

data/           synthetic corpora and evaluation data
docs/           architecture and refactor notes
templates/      source templates adapted into project docs
tests/          contract, unit, and end-to-end tests
runs/           trace outputs

Synthetic data is organized by intent:

data/demo/       small demo corpus
data/eval/       deliberate architectural evaluation scenarios
data/fixtures/   tiny deterministic unit-test fixtures

Legacy corpus roots remain available for compatibility: data/corpus_phase1 for the canonical demo and data/corpus for the older phase2 corpus. Manifest doc_id values are the stable citation/source identities emitted as evidence source_ids; document paths are normalized to corpus-root-relative POSIX strings.

AI-Native Development

This repository is built with an AI-native workflow: human architectural ownership, Codex-assisted implementation, deterministic tests, and trace-based review.

For project-specific agent instructions, see AGENTS.md.

For the build-process journal, see AI_native_builder_journal.md.

License

InterAgents is released under the MIT License. See LICENSE.