🌉 AgentBridge

Turn your existing system into an AI-agent-ready platform — in seconds.

AgentBridge discovers capabilities from your API schemas, database schemas, and source routes, then generates a complete Agent Integration Kit that works with MCP, Claude, OpenAI, and Vercel AI SDK out of the box.

With built-in Claude Agent SDK support and AI-powered dynamic generation, AgentBridge goes beyond static templates — it uses AI to craft richer tool definitions, domain-specific skills, and intelligent prompts tailored to your system.

✨ Features

🔍 Auto-discovery Extracts capabilities from OpenAPI, GraphQL, SQL, and source code routes (Python/Flask/FastAPI, JS/Express, Java/Spring)	🔧 Multi-format Generation Outputs MCP, Claude, OpenAI, and Vercel AI SDK tool definitions simultaneously
🤖 AI-Powered Generation Uses Claude Agent SDK (primary) or Anthropic API (fallback) to dynamically generate tools, skills, and prompts	🧠 Agent as a Service Runs as an interactive agent for your existing project via Claude Agent SDK
🛡️ Safety-first Classifies operations by risk level with human-in-the-loop confirmation for dangerous actions	🧪 Dry-run Validation Test tool invocations against generated guardrails before executing
🌐 Custom LLM Providers Supports DeepSeek, OpenRouter, and any Anthropic-compatible endpoint	🪶 Rules + LLM Combined Rule-based analysis (risk keywords, HTTP verbs) feeds into LLM as context for smarter generation

🚀 Quick Start

Installation

pip install agbr

📦 Install with optional features

# AI-powered generation + agent sessions (recommended)
pip install "agbr[agent]"

# Lightweight AI generation (no Claude Agent SDK)
pip install "agbr[ai]"

# Everything
pip install "agbr[all]"

# Install from source (for development)
git clone git@github.com:jastfkjg/AgentBridge.git
cd AgentBridge
pip install -e ".[all]"

Configure LLM Provider

AgentBridge requires an LLM API key for all generation. By default it uses Anthropic's Claude, but you can configure any Anthropic-compatible provider:

# Required
export ANTHROPIC_API_KEY="sk-ant-..."

# Optional: Custom API endpoint
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"   # DeepSeek
# export ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1"       # OpenRouter

# Optional: Custom model name
export ANTHROPIC_MODEL="deepseek-v4-flash"

🔑 Or pass via CLI flags

agentbridge generate examples/writing_system --output build/kit \
  --api-key "sk-..." \
  --base-url "https://api.deepseek.com/anthropic" \
  --model "deepseek-v4-flash"

Note: When ANTHROPIC_BASE_URL is set, AgentBridge automatically uses the anthropic SDK backend (not claude-agent-sdk) for generation, since custom endpoints are not supported by the agent SDK.

Generate an Agent Integration Kit

# Requires ANTHROPIC_API_KEY (set via env var or --api-key flag)
agentbridge generate examples/writing_system --output .agentbridge/writing-kit

Run as an Agent

agentbridge chat .agentbridge/writing-kit

Run Tests

PYTHONPATH=src python -m unittest discover -s tests

📖 CLI Reference

Command	Description
`agentbridge discover <paths>`	Discover and print capabilities as JSON
`agentbridge generate <paths> -o <dir>`	Generate an Agent Integration Kit
`agentbridge dry-run <kit> <tool>`	Dry-run a tool invocation
`agentbridge chat <kit>`	Start an interactive AI agent session

📝 Full command details

`discover`

agentbridge discover examples/writing_system

`generate`

agentbridge generate examples/writing_system --output build/agent-kit

# With custom name
agentbridge generate examples/writing_system --output build/agent-kit --name my-kit

# With custom LLM provider
agentbridge generate examples/writing_system --output build/agent-kit \
  --api-key "sk-..." --base-url "https://api.deepseek.com/anthropic" --model "deepseek-v4-flash"

`dry-run`

# Normal invocation
agentbridge dry-run build/agent-kit create_chapter --args '{"project_id":"p1","title":"Opening"}'

# High-risk operation (requires confirmation)
agentbridge dry-run build/agent-kit delete_character \
  --args '{"project_id":"p1","character_id":"c1"}' --confirmed

`chat`

agentbridge chat build/agent-kit
# Or with custom LLM provider:
agentbridge chat build/agent-kit --api-key "sk-..." --base-url "https://api.deepseek.com/anthropic"

🔍 What AgentBridge Discovers

Source Type	Formats
🌐 API Schemas	OpenAPI JSON/YAML, GraphQL schemas
🗄️ Database Schemas	SQL `CREATE TABLE` statements
🐍 Python Routes	FastAPI `@router.get/post/...`, Flask `@app.route`
📜 JavaScript Routes	Express `app.get/post/...`
☕ Java Routes	Spring `@GetMapping/@PostMapping/...`

All sources are normalized into a common capability model with:

Field	Description
`domain` + `resource`	Logical grouping
`action`	What the capability does
`input_schema`	JSON Schema parameters
`risk`	`read` / `write` / `destructive` / `external_side_effect`
`confirm_required`	Whether human approval is needed
`source`	Full traceability back to the origin file

📁 Generated Kit Layout

agent-kit/
├── manifest.json                  # Kit metadata and summary
├── capabilities.json              # All discovered capabilities
├── tools/
│   ├── mcp_tools.json             # MCP tool definitions
│   ├── openai_tools.json          # OpenAI function calling format
│   ├── claude_tools.json          # Claude tool use format
│   └── vercel_ai_tools.ts         # Vercel AI SDK TypeScript tools
├── skills/
│   └── writing.md                 # Domain-specific skill definitions
├── prompts/
│   └── system.md                  # Agent system prompt
├── resources/
│   └── schema.json                # Resource schema summary
├── guardrails/
│   └── permissions.json           # Risk policy and confirmation rules
├── tests/
│   ├── tool_invocation_tests.json # Auto-generated invocation tests
│   └── test_generated_tools.py    # Python unit tests for tool contracts
└── dry_run_plan.json              # Dry-run execution plan

🤖 AI-Powered Generation

AgentBridge uses LLM to generate all content — tool descriptions, skills, system prompts, risk assessments, and inferred tools. Rule-based analysis (keyword matching, HTTP verb classification) is fed into the LLM as context, not used directly.

What	Description
📝 Enhanced tool descriptions	Context-aware descriptions that capture business semantics
🎯 Domain-specific skills	Workflow prompts tailored to your domain with best practices
🧠 Intelligent system prompts	Prompts that understand resource relationships and suggest safe sequences
🔍 Inferred additional tools	Tools implied by your schema but not explicitly present
⚠️ Improved risk assessments	LLM evaluates risk with rule-based hints as context

AI Backend

Backend	Package	Use Case
Claude Agent SDK (primary)	`claude-agent-sdk`	Generation + interactive agent sessions
Anthropic API (fallback)	`anthropic`	Generation only, supports custom endpoints

When claude-agent-sdk is installed and no custom ANTHROPIC_BASE_URL is set, it is used automatically. When a custom endpoint is configured or claude-agent-sdk is not installed, the anthropic SDK is used.

Programmatic Usage

from pathlib import Path
from agentbridge.generator import AgentKitGenerator
from agentbridge.agent import AIGenerator, AgentRunner

# Generate with default provider (Anthropic Claude)
ai = AIGenerator(api_key="sk-ant-...")
kit = AgentKitGenerator(ai_generator=ai).generate(
    [Path("examples/writing_system")],
    Path("build/agent-kit"),
)

# Custom LLM provider (e.g., DeepSeek)
ai = AIGenerator(
    api_key="sk-d831ecabc21842fdae6f30c24dd3b052",
    base_url="https://api.deepseek.com/anthropic",
    model="deepseek-v4-flash",
)

# Agent session
import asyncio
async def main():
    runner = AgentRunner(kit_dir="build/agent-kit", api_key="sk-ant-...")
    async for message in runner.query("List all chapters in project p1"):
        print(message)
asyncio.run(main())

🛡️ Safety Model

Risk Level	Confirmation	Examples
🟢 `read`	Not required	GET, list, search, find
🟡 `write`	Optional by policy	POST, create, update, rewrite
🔴 `destructive`	Required	DELETE, remove, destroy, drop, cancel
🟠 `external_side_effect`	Required	publish, send, email, pay, deploy, export

The safety model is applied consistently. Rule-based risk classification provides initial context, and the LLM may override when justified.

🏗️ Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Discovery   │────▶│  Generator   │────▶│  Agent Kit      │
│  (schemas,   │     │  (LLM-driven │     │  (tools, skills,│
│   routes,    │     │   + rules as │     │   prompts,      │
│   SQL)       │     │   context)   │     │   guardrails)   │
└─────────────┘     └──────┬───────┘     └────────┬────────┘
                           │                      │
                    ┌──────▼───────┐       ┌──────▼────────┐
                    │  AI Generator│       │  Agent Runner │
                    │  (Claude SDK │       │  (Claude SDK  │
                    │   / Anthropic│       │   Client +    │
                    │   API)       │       │   MCP Tools)  │
                    └──────────────┘       └───────────────┘

🧩 Extending AgentBridge

Extension	How
New schema parser	Implement a discoverer in `discovery.py`
New tool format	Add a builder function in `generator.py`
Custom AI prompts	Override prompts in `agent.py`
Custom risk policy	Modify `policy.py`
Custom agent tools	Extend `AgentRunner._build_kit_tools()`

📦 Publishing & Installation

🔧 How does `pip install "agbr"` work?

AgentBridge is packaged as a standard Python package using pyproject.toml + setuptools. Here's the mechanism:

1. Package Structure

AgentBridge/
├── pyproject.toml          # Package metadata, dependencies, entry points
├── src/
│   └── agentbridge/        # Actual Python package
│       ├── __init__.py
│       ├── cli.py          # CLI entry point
│       ├── agent.py
│       ├── generator.py
│       └── ...
└── tests/

2. `pyproject.toml` Key Sections

[project]
name = "agbr"                    # pip install agbr
version = "0.2.0"

[project.optional-dependencies]         # pip install "agbr[agent]"
agent = ["claude-agent-sdk>=0.1.0"]
ai = ["anthropic>=0.30.0"]

[project.scripts]
agentbridge = "agentbridge.cli:main"    # CLI entry point

[tool.setuptools.packages.find]
where = ["src"]                         # Code lives in src/

3. How `pip install` Works

Build: pip reads pyproject.toml, uses setuptools to build a wheel (.whl)
Install: The wheel is installed into your Python environment's site-packages/
CLI: The [project.scripts] section creates a agentbridge executable in your PATH that calls agentbridge.cli:main

4. Publishing to PyPI (so anyone can `pip install`)

# Build the package
pip install build
python -m build

# Upload to TestPyPI (for testing)
pip install twine
twine upload --repository testpypi dist/*

# Upload to PyPI (for real)
twine upload dist/*

After publishing, anyone can run pip install "agbr".

5. Installing Without PyPI

Until the package is published on PyPI, users can install it in these ways:

# Install from local source (editable mode, for development)
pip install -e .

# Install from GitHub repository
pip install git+ssh://git@github.com/jastfkjg/AgentBridge.git

# Install from a local wheel
pip install dist/agentbridge-0.2.0-py3-none-any.whl

🤝 Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please make sure tests pass:

PYTHONPATH=src python -m unittest discover -s tests -v

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github/workflows		.github/workflows
examples/writing_system		examples/writing_system
src/agentbridge		src/agentbridge
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
_test_integration.py		_test_integration.py
_test_llm.py		_test_llm.py
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

🌉 AgentBridge

📑 Table of Contents

✨ Features

🚀 Quick Start

Installation

Configure LLM Provider

Generate an Agent Integration Kit

Run as an Agent

Run Tests

📖 CLI Reference

discover

generate

dry-run

chat

🔍 What AgentBridge Discovers

📁 Generated Kit Layout

🤖 AI-Powered Generation

AI Backend

Programmatic Usage

🛡️ Safety Model

🏗️ Architecture

🧩 Extending AgentBridge

📦 Publishing & Installation

1. Package Structure

2. pyproject.toml Key Sections

3. How pip install Works

4. Publishing to PyPI (so anyone can pip install)

5. Installing Without PyPI

🤝 Contributing

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`discover`

`generate`

`dry-run`

`chat`

2. `pyproject.toml` Key Sections

3. How `pip install` Works

4. Publishing to PyPI (so anyone can `pip install`)

Packages