AgentBridge

AgentBridge automatically parses existing projects and systems into a versioned tool layer controllable by Claude Agent chat. It discovers system evidence, normalizes it into capabilities, packages those capabilities as an Agent Integration Kit, and exposes the kit through Claude Agent SDK, MCP, terminal chat, and Web Chat.

Existing project/system
  -> parse project/API/DB/GraphQL/job evidence
  -> normalized capabilities
  -> Agent Integration Kit
  -> Claude Agent SDK / MCP / Web Chat
  -> controlled APIs / DB / GraphQL / background jobs

中文

What It Provides

• AI-first project analysis with Claude Agent SDK.
• Candidate discovery from OpenAPI, GraphQL, SQL, gRPC proto files, explicit Python plugins, and source routes.
• A stable agentbridge-kit/v1 contract containing capabilities, tools, prompts, skills, schemas, guardrails, dry-run plans, client configs, and tests.
• Claude Agent SDK, MCP, Claude, OpenAI, and Vercel AI tool definitions generated from the same capability model.
• Browser and terminal chat control surfaces over the generated tool layer.
• Dry-run by default, runtime policy controls, structured runtime errors, audit redaction, and human-in-the-loop authorization.
• Richer project understanding: OpenAPI $ref/JSON Schema normalization, AST-backed Python route discovery, structured TypeScript/Java source scanning, evidence links, confidence scores, and human-readable analysis reports.
• CI-oriented kit quality: agentbridge diff, generate --check, additive kit migration, and preservation of user-authored prompts, skills, and guardrails during regeneration.
• Session history, streaming Web Chat responses, tool timelines, clickable tool invocation, required-parameter guidance, file attachments, and AI token usage/cost metadata.
• In-place re-analysis of an existing kit when the source system changes.

Runtime adapters now cover HTTP/OpenAPI, GraphQL POST operations, SQLite read-only SQL SELECT tools, gRPC via grpcurl, and explicit Python plugin dry-run/execute hooks. Dry-run remains the default for every transport.

Install

pip install "agbr[agent]"

Project analysis and agentbridge enhance require:

export ANTHROPIC_API_KEY="..."

Optional Anthropic-compatible endpoint:

export ANTHROPIC_BASE_URL="https://api.example.com/anthropic"
export ANTHROPIC_MODEL="your-model"

Generate a Kit

Analyze a project directory with Claude Agent SDK:

agentbridge generate ./my-system \
  --output .agentbridge/my-system-kit \
  --analysis-mode agentic

For schema-only deterministic generation:

agentbridge generate ./openapi.json \
  --output .agentbridge/openapi-kit \
  --no-ai

Validate the result:

agentbridge validate .agentbridge/my-system-kit

Check whether an existing generated kit is stale without rewriting it:

agentbridge generate ./openapi.json \
  --output .agentbridge/openapi-kit \
  --no-ai \
  --check

Compare two generated kits for CI review:

agentbridge diff .agentbridge/old-kit .agentbridge/new-kit

Enhance an Existing Kit

Re-analyze the current project and update the existing kit in place:

agentbridge enhance .agentbridge/my-system-kit ./my-system

This command always uses Claude Agent SDK. Existing AI-inferred capabilities are retained as a baseline, current project evidence is rescanned, duplicate operations are consolidated, and changed or new capabilities are regenerated.

Use --resume to reuse valid batch checkpoints:

agentbridge enhance .agentbridge/my-system-kit ./my-system --resume

Start the System Control Console

agentbridge web .agentbridge/my-system-kit --port 8765

Open the printed URL. The Web home page is a responsive System Control Console over the parsed system:

• Seven deep-linked workspaces: Chat, Tools, Capabilities, Policy, Audit, Workflows, and Settings.
• Searchable risk-aware tool and capability catalogs; preparing a tool returns to Chat without executing it.
• Editable generated policy, redacted audit events, inferred workflow guidance, and kit/runtime settings.
• Dry-run and real-system switching, Base URL connectivity checks, saved accounts, token usage, and responsive mobile navigation.
• Real-time SSE chat, command details, interrupt control, conversation management, attachments, Markdown, and explicit high-risk authorization.

Real-system mode still enforces generated guardrails and confirmation requirements. By default, read tools may execute when execute mode is enabled, write tools require confirmation, destructive tools are denied, and external-side-effect tools require confirmation.

Runtime credentials can be supplied when starting the server:

agentbridge web .agentbridge/my-system-kit \
  --base-url http://localhost:8080 \
  --bearer-env API_TOKEN \
  --execute

Web Chat stores the selected Base URL in <kit>/.agentbridge-runtime.json so reopening the same kit restores the target. When Save login is enabled and a real-system login call uses username/password arguments or returns access_token, token, jwt, an Authorization header, or Set-Cookie, Web Chat stores the runtime credentials in the same local state file. Multiple login accounts can be saved per kit; the Web UI exposes a saved-account selector plus add/edit/delete controls, and only sends the selected account id back to the server during normal chat turns. If a generated HTTP tool receives HTTP 401 with a token-expired response, AgentBridge refreshes authentication once with the selected saved account before retrying the original tool. This file is ignored by git and is not part of the generated kit protocol.

The Web Chat server prints concise request, stream, permission, and error logs to the terminal. Sensitive values such as passwords, tokens, cookies, and API keys are redacted.

Start Terminal Chat

agentbridge chat .agentbridge/my-system-kit

Useful commands:

/tools
/use
/run <tool> key=value
/mode dry-run
/mode execute http://localhost:8080
/connect http://localhost:8080
/usage
/history

/use provides numbered tool selection and prompts for required parameters. High-risk operations provide an explicit Authorize/Cancel choice.

Run as an MCP Server

Expose the generated Agent Integration Kit as MCP tools.

Dry-run:

agentbridge serve .agentbridge/my-system-kit

Real HTTP execution:

agentbridge serve .agentbridge/my-system-kit \
  --base-url http://localhost:8080 \
  --bearer-env API_TOKEN \
  --execute

GraphQL, SQL, and gRPC tools use transport-specific runtime targets:

agentbridge serve .agentbridge/my-system-kit \
  --graphql-endpoint http://localhost:8080/graphql \
  --database-url sqlite:///tmp/app.db \
  --grpc-target 127.0.0.1:50051 \
  --execute

Generate client configuration:

agentbridge mcp-config .agentbridge/my-system-kit --write

Safety Defaults

• Dry-run never executes the target operation.
• Read tools may execute in execute mode.
• Write tools require explicit confirmation.
• Destructive tools are denied by the generated policy unless an operator changes the kit policy.
• External-side-effect tools require explicit confirmation.
• Runtime failures use structured error codes such as permission_denied, schema_mismatch, http_error, timeout, and adapter_error.
• Audit logs redact passwords, tokens, cookies, authorization headers, API keys, and secrets.
• Switching runtime mode clears pending authorization.
• Project analysis is read-only; generated files are written only to the selected kit directory.
• Secrets are runtime inputs and must not be stored in generated kit protocol files. Web Chat credentials live in local runtime state (.agentbridge-runtime.json), which should stay out of version control.

Main Commands

Command	Purpose
discover <paths>	Print deterministic candidate capabilities
generate <paths> -o <kit>	Generate a Claude-controllable Agent Integration Kit
generate <paths> -o <kit> --check	Fail when the existing kit differs from regenerated output
diff <old-kit> <new-kit>	Compare capability, risk, schema, transport, and guardrail changes
enhance <kit> <paths>	Re-analyze and update an existing kit with Claude Agent SDK
validate <kit>	Validate kit protocol and safety contracts
validate <kit> --migrate	Apply additive v1 migrations before validation
doctor <kit>	Check runtime readiness
web <kit>	Start browser chat over the tool layer
chat <kit>	Start terminal chat over the tool layer
serve <kit>	Expose the kit as a stdio MCP server
dry-run <kit> <tool>	Preview one tool invocation
mcp-config <kit>	Generate MCP client configuration

Documentation

• Architecture
• Chat and Web UI
• MCP runtime
• Kit protocol
• Chinese documentation

Development

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

License

MIT