OpenAPI → Agent Bridge

Convert any OpenAPI/Swagger spec into an Agenium agent automatically.

Quick Start

npx openapi-agent-bridge \
  --spec ./api.yaml \
  --api-key dom_your64hexkey \
  --name myapi

Features

• OpenAPI 3.x & Swagger 2.x support
• Auto-maps endpoints to agent capabilities
• Generates Agent Card with full capability descriptions
• Proxy server: receives agent:// JSON-RPC → converts to REST API calls
• Auth pass-through: Bearer, API key, OAuth2
• Hot-reload: watches spec file for changes
• Graceful shutdown: auto-unregisters from DNS

Installation

npm install -g openapi-agent-bridge
# or
npx openapi-agent-bridge --spec ./api.yaml --api-key dom_... --name myapi

Options

Flag	Description	Default
--spec <path>	Path to OpenAPI/Swagger spec	required
--api-key <key>	Agenium API key (dom_...)	required
--name <name>	Agent name for DNS	required
--dns <url>	DNS server URL	http://185.204.169.26:3000
--port <n>	Proxy server port	3100
--base-url <url>	Override API base URL	from spec
--auth-type <type>	bearer, apikey, oauth2, none	none
--auth-token <tok>	Auth token for upstream API	—
--auth-header <h>	Custom auth header name	X-API-Key
--hot-reload	Watch spec for changes	false
--card-only	Print agent card JSON and exit	false

How It Works

1. Parses your OpenAPI spec
2. Converts each endpoint to an agent capability
3. Generates an Agent Card (.well-known/agent.json)
4. Starts a proxy server that translates JSON-RPC → REST
5. Registers with Agenium DNS

Other agents can then discover and call your API via agent://myapi.agenium.

Example

# Register the Petstore API
./examples/register-petstore.sh dom_your64hexkey

# Query it via agent protocol
curl -X POST http://localhost:3100 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"listPets","params":{"limit":10},"id":"1"}'

License

MIT

Bug Reporting

This project includes optional bug reporting to the Agenium monitoring server.

Configuration

Set the following environment variables to enable bug reporting:

BUG_REPORT_URL=http://130.185.123.153:3100
BUG_REPORT_TOKEN=your_token_here

Bug reporting is disabled by default — it only activates when BUG_REPORT_TOKEN is set. Reports are sent asynchronously (fire and forget) and never block the main application.