agbr 0.3.2

Generate Agent Integration Kits for existing systems with AI-powered dynamic generation via Claude Agent SDK.

🌉 AgentBridge

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

English · 中文

---

AgentBridge uses an AI analysis agent to understand your project code, then generates a complete Agent Integration Kit that works with MCP, Claude, OpenAI, and Vercel AI SDK out of the box.

Deterministic scanners still collect candidate evidence from OpenAPI, GraphQL, SQL, and source routes, but they are not the source of truth. The AI agent reads the project context, reasons about business objects and side effects, then creates tools, skills, prompts, guardrails, tests, and protocol metadata.

📑 Table of Contents

• ✨ Features
• 🚀 Quick Start
• 📖 CLI Reference
• 🔍 How AgentBridge Analyzes Projects
• 🔍 Candidate Evidence Sources
• 📁 Stable Kit Protocol
• 🤖 AI Agent Generation
• 🛡️ Safety Model
• 🏗️ Architecture
• 📚 Documentation
• 🧩 Extending AgentBridge
• 📦 Publishing & Installation
• 🤝 Contributing
• 📄 License

---

✨ Features

🔍 AI-first code analysis Uses an AI agent to interpret business objects, workflows, permissions, and side effects from project code	🔧 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 as evidence OpenAPI, GraphQL, SQL, and route scanners provide candidate signals for the AI agent to verify or override

---

🚀 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 [e-mail]: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>	Analyze code with AI and 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"

---

🔍 How AgentBridge Analyzes Projects

AgentBridge is designed so the AI agent performs the main project understanding step. Rule-based discovery is intentionally conservative and acts as evidence collection.

Stage	Role
Candidate scanning	Extract OpenAPI operations, GraphQL fields, SQL tables, and route handlers
AI project analysis	Infer business objects, workflows, permission boundaries, side effects, missing operations, and assumptions
Capability normalization	Convert the AI-enhanced analysis into stable tool-ready capabilities
Kit generation	Emit tools, skills, prompts, resource schemas, guardrails, dry-run plans, and tests

The generated kit preserves both layers:

• analysis/rule_signals.json: deterministic candidate evidence
• analysis/agent_analysis.json: AI agent project analysis and reasoning

🔍 Candidate Evidence Sources

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

---

📁 Stable Kit Protocol

Current protocol: agentbridge-kit/v1. See docs/kit-protocol.md.

agent-kit/
├── manifest.json                  # Kit metadata and summary
├── capabilities.json              # AI-enhanced normalized capabilities
├── analysis/
│   ├── rule_signals.json          # Scanner evidence used as AI context
│   └── agent_analysis.json        # AI project analysis and risk reasoning
├── spec/
│   └── kit-protocol.md            # Protocol contract copied into the kit
├── 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 Agent Generation

AgentBridge uses an AI analysis agent to generate the semantic parts of the kit: project analysis, tool descriptions, skills, system prompts, risk assessments, and inferred tools. Rule-based analysis is passed to the agent as candidate evidence and safety hints, not copied directly as final output.

What	Description
🧭 Project analysis	Business objects, workflows, permission boundaries, side effects, and assumptions
📝 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

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│ Rule Signals │────▶│ AI Analysis │────▶│ Kit Generator   │
│ (schemas,    │     │ Agent       │     │ (protocol v1)   │
│  routes, SQL)│     │             │     │                 │
└─────────────┘     └──────┬──────┘     └────────┬────────┘
                           │                     │
                    ┌──────▼──────┐       ┌──────▼────────┐
                    │ Capabilities│       │ Agent Runtime │
                    │ Skills      │       │ Dry-run +     │
                    │ Guardrails  │       │ Guardrails    │
                    └─────────────┘       └───────────────┘

---

📚 Documentation

• Architecture
• Kit protocol
• 中文 README
• 中文架构说明
• 中文套件协议

---

🧩 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

1. Build: pip reads pyproject.toml, uses setuptools to build a wheel (.whl)
2. Install: The wheel is installed into your Python environment's site-packages/
3. 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://[e-mail]/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:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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.