AgentBridge

AgentBridge

🔌 Add Agent capabilities to your business systems — knowledge retrieval, data analysis, structured output, human-in-the-loop approval — without changing a single line of existing code.

Built for Vibe Coding: let AI coding assistants write your plugins.

简体中文 · Documentation · Architecture rules · Vibe Coding Guide

Whether your system is a government service platform, enterprise ERP, device management tool, or internal ops dashboard — if it has APIs or a database, AgentBridge can add an Agent layer alongside it. Users describe what they need in natural language. The Agent pulls from your business data and dynamically generates tables, charts, and reports. Write operations go through human approval.

No changes to existing systems. No data migration. No cloud dependency. Runs on your own machines, MIT licensed.

🏗️ How it works without changing your code

AgentBridge doesn't touch your business systems. It adds an adapter layer next to your existing APIs — you write a plugin that describes what your APIs can do, and AgentBridge handles everything else.

You write the plugin, the platform handles the rest:

🔩 Under the hood

AgentBridge is a source-first Python platform with explicit boundaries between reusable runtime code, host wiring, and business plugins.

The request path is:

Client → FastAPI route → RunLifecycle → registered business graph/tools
       ← Nginx / SSE ← recorded outbound events and structured extensions

apps/api/lifespan.py is the production composition root: it creates adapters, registers plugins, and injects implementations into the runtime. packages/core never imports a concrete business plugin, and plugins do not create infrastructure adapters or emit SSE directly. See the architecture summary, event contracts, and non-negotiable rules.

The default Compose stack starts the React console, FastAPI service, and PostgreSQL with pgvector. Redis and Authentik are optional profiles. The v1.0.0 single-node release includes an offline model stub and fake knowledge backend for deterministic verification, while Postgres-backed business data and approval execution exercise the complete demo flow. Real OpenAI-compatible models and external RAG are opt-in integrations. For an environment default, set LLM_MODE=openai_compatible with an OpenAI-compatible endpoint, model, and key. The repository .env is persistently mounted into the API, so an administrator can re-authenticate in the console's Models page to generate and save MODEL_CONFIG_ENCRYPTION_KEY during both direct development and Compose use. Model API keys are encrypted at rest and never returned to the browser.

🤖 Vibe Coding Integration

AgentBridge is built for Vibe Coding. You don't need to write code yourself — let Cursor, Codex, Claude Code, or other AI assistants write the plugin for you.

Three steps:

1. Clone the repo, open it in your AI coding assistant
2. Point the assistant to SKILL.md
3. Describe your business system — the assistant writes the plugin

Read SKILL.md, then help me integrate my business system.

My system: <one sentence about what it does>
My APIs: <list your endpoints or database tables>
What users will ask: <a few real examples>

Detailed guide and copy-ready prompts in SKILL.md.

🎯 When to use it

You already have APIs or databases and want to add Agent capabilities — whether it's a prototype for stakeholders or a real tool for your team.

• 🔍 Product validation: Quickly show "our system can do AI-powered data analysis"
• ⚡ Internal efficiency: Add a natural language entry point to existing systems
• 🔗 Shared governance: Multiple systems sharing one set of permissions, approvals, and audit

⚠️ When NOT to use it

• 🚫 Building an AI product from scratch (no existing APIs) → Use LangGraph, CrewAI, or similar
• 🚫 High-frequency real-time trading (Agent adds 1–3s latency) → Use a traditional API gateway
• 🚫 Replacing your entire auth system → AgentBridge integrates with your login, but doesn't replace it
• 🚫 Multi-node scaling out of the box → Requires explicit configuration

Simple test: your system has APIs, you want AI to call them with permission and approval controls — use AgentBridge. You're building an AI product from scratch — you don't need it.

🚀 Run it and see for yourself

git clone https://github.com/Foamtor/AgentBridge.git
cd AgentBridge
docker compose up --build

The Compose demo defaults to the DaoCloud registry mirror for China. To use official Docker Hub paths instead, set IMAGE_REGISTRY=docker.io in .env.

Open http://localhost:8080. On the first start, retrieve the one-time administrator password from the API log:

docker compose logs api

Sign in as admin, set a strong new password, then use the Verification Workbench to run work_order_ops.

For daily plugin work, open /playground: it keeps request composition, thread history, live SSE, timing, tool traces, contract checks, JSONL export, and badcase annotations together. See Plugin Playground for Fake versus real-model reference-case setup.

If you set WEB_PORT, use that port instead.

💡 No API key or cloud service needed. The Compose demo includes PostgreSQL, an offline model, and synthetic demo data. The initial password is never committed or fixed in the image.

Details in the quick-start guide.

📋 A complete example

The repo includes a reference implementation called work_order_ops that walks through a full business loop.

All demo data is synthetic. It's not a finished product — it's a template for building your own plugin.

📦 What the platform does

🗂️ Repository structure

packages/core/          Platform core: lifecycle, protocols, adapters
apps/api/               Service entry: routes, composition
│   └── domains/        Your business plugins go here
│       ├── _scaffold/  Plugin template
│       └── work_order_ops/  Reference implementation
apps/web/               Debug console
packages/sdk/           TypeScript client
docs/                   Documentation
SKILL.md                Vibe Coding integration guide (for AI assistants)

📊 Current status

• ✅ v1.0.0 single-node stable release
• ℹ️ Real Docker Compose golden smoke is environment-dependent and should be run before deployment
• ✅ Reference work_order_ops implementation included
• ✅ Python, API, core, Web, architecture, and release-document gates pass
• 🚧 Production deployment drills, migration/recovery, concrete IdP integration, multi-instance validation, and package publishing are post-1.0 follow-up work

🤝 Contributing

1. Fork → Branch → PR
2. Read CONTRIBUTING.md for code standards
3. Use only redacted example data — never commit real business data

📄 License

MIT © Foamtor

Find it useful? Give us a ⭐ Star!