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.