How codered-dev/ai-agent-bridge works
What this project is (type + purpose)
This is a Python library/scaffold for a multi-agent communication “bridge” that standardizes agent-to-agent interactions via a structured message protocol rather than freeform chat. It’s not a full-stack web app; it’s a protocol + router + adapters package with a local demo.
• Agents don’t talk directly; they communicate by exchanging typed protocol envelopes (AgentMessage) through a Router/Bridge layer that validates, enforces handshake/lifecycle transitions, and records events.
• Model execution is decoupled via an adapter interface: the bridge is model-agnostic, and concrete adapters implement the “call LLM + parse response” integration.
Core package: src/bridge/
• protocol.py: domain model (message schema, statuses, TTL, serialization) + MessageQueue (in-memory transport abstraction).
• adapter.py: AgentAdapter (interface/base class) that defines how an agent sends/receives intents via the bridge; declares integration points:
• prompt_model / parse_response (implemented by concrete adapters).
• router.py: Router / Bridge orchestrator
• enforces handshake transitions
• records router events (observability)
• maintains a shared context store (metadata/journaling per conversation)
• delivers validated requests to target agent(s)
• local_llm.py: Local LLM client wrapper (stub or Ollama runner); represents the “LLM backend” boundary.
• local_adapter.py: LocalLLMAdapter concrete adapter that:
• pulls shared context
• builds structured prompts
• sends replies back through router
Runtime/demo + artifacts
• scripts/handshake_demo.py: the composition root (wires planner/executor adapters + router + stubbed or real local clients).
• logs/bridge.log: runtime event log output; important for observability lane.
• docs/architecture.md, docs/plan.md, docs/use_case.md: these define intended architecture—use them to justify components/flows.
• results/*: experimental outputs; these are not architecture components but help validate flows.
Handshake / lifecycle control (Router-centric)
• Planner Adapter → Router: “HELLO/READY” (or initial registration/handshake message)
• Router → Planner Adapter: ACK / transition allowed
• Executor Adapter ↔ Router: same handshake
• Router updates internal state machine and logs events.
• state transitions enforced by Router
• status values (ready, working, error, etc.) as part of the envelope
Router
• validates schema + TTL
• enriches with shared context metadata (conversation store)
• records event
Observability lane (should be explicit)
• Router → logs/bridge.log: append structured router events
Optionally show:
• Router events store (in-memory list) + file sink
Architectural patterns/design principles to highlight
• Protocol-first design: AgentMessage is the contract; adapters and router revolve around it.
• Adapter pattern: AgentAdapter abstracts the LLM integration; concrete implementations swap backends without changing routing logic.
• Decoupled reasoning/execution: Planner and Executor are independent agents connected via bridge.
• State machine / handshake enforcement: Router controls allowed transitions and message lifecycles.
• Pluggable transport: MessageQueue is currently in-memory but represents a replaceable messaging substrate (future HTTP/WS).
• Router (src/bridge/router.py)
• “handshake enforcement”
• “shared context store”
• “event recorder”
• Protocol (src/bridge/protocol.py)
• “AgentMessage schema”
• “MessageStatus + TTL”
• “(In-memory) MessageQueue”
• AgentAdapter (base) (src/bridge/adapter.py)
• “send_intent / receive_message”
• “prompt_model + parse_response hooks”
• LocalLLMAdapter (src/bridge/local_adapter.py)
• LocalLLMClient (src/bridge/local_llm.py)
• “stub runner / Ollama runner”
• Handshake demo (scripts/handshake_demo.py)
• Logs (logs/bridge.log)
“Don’t overthink it”: split into as many components as possible (for this repo)
Because this is a scaffold, accuracy improves by explicitly drawing even “small” elements:
• separate Protocol schema from Router from Transport
• separate Adapter base from Local adapter from LLM client
• separate Handshake/lifecycle from Intent routing from Logging
That granularity matches the file structure and makes it clear which pieces are stable contracts vs. pluggable integrations.