agno-relay

v1.0.1

Published

13 days ago

> **Note**: This project is unrelated to [agno-agi/agno](https://github.com/agno-agi/agno) (Python agent framework).

0High
0Medium
0Low

getrift

Note: This project is unrelated to agno-agi/agno (Python agent framework).

agno

A reliability bridge that translates MCP tool servers into an OpenAI-compatible tools interface with deterministic behavior under failures.

Point agno at any MCP server and immediately call it via an OpenAI-style POST /v1/chat/completions flow, with a canonical error contract that agents can reliably interpret.

Features

OpenAI-Compatible API — Drop-in replacement for tool calling workflows
Canonical Error Contract — 8 deterministic error classes with retry guidance
Pagination Normalization — Opaque cursor-based pagination for all list operations
Idempotency Support — Safe retries for mutations with X-Idempotency-Key
Auth Handling — Bridge-level credentials or per-request passthrough
Trace Mode — Side-by-side request/response debugging
Conformance Reports — README-ready markdown + CI-friendly JSON

Quick Start

# Install dependencies
npm install

# Build
npm run build

# Start the bridge
node dist/cli.js bridge --url http://localhost:3000

# Or with npx (when published)
npx agno-relay bridge --url http://localhost:3000

Output:

🚀 Bridge ready

Endpoint: http://localhost:3847/v1/chat/completions
Upstream: http://localhost:3000

Capabilities:
  • Streaming: unsupported
  • Pagination: cursor-based
  • Errors: canonical
  • Auth: bridge-level

Usage

Bridge Command

agno-relay bridge --url <mcp_server_url> [options]

| Option | Description | Default | |--------|-------------|---------| | --url <url> | MCP server URL (required) | — | | --port <number> | Local port | 3847 | | --allow-auth-passthrough | Forward Authorization header | false | | --trace | Enable debug output | false |

Report Command

agno-relay report [options]

| Option | Description | Default | |--------|-------------|---------| | --format <format> | Output format (markdown or json) | markdown |

API Reference

POST /v1/chat/completions

OpenAI-compatible chat completions endpoint with tool calling support.

Request:

{
  "model": "gpt-4",
  "messages": [
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_1",
          "type": "function",
          "function": {
            "name": "list_repos",
            "arguments": "{\"org\": \"acme\"}"
          }
        }
      ]
    }
  ]
}

Response:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_1",
            "type": "function",
            "function": {
              "name": "list_repos",
              "arguments": "{\"result\": ...}"
            }
          }
        ]
      }
    }
  ]
}

GET /healthz

Health check endpoint.

{"status": "ok"}

GET /capabilities

Bridge capabilities.

{
  "streaming": false,
  "pagination": "cursor",
  "errors": "canonical",
  "auth": "bridge-level"
}

Canonical Error Contract

Every failure returns a structured error envelope:

{
  "error": {
    "class": "rate_limit",
    "retryable": true,
    "suggested_backoff_ms": 2500,
    "message": "GitHub API rate limit exceeded.",
    "action": "wait_and_retry",
    "context": {
      "source": "upstream",
      "upstream_code": 429,
      "reset_at": 1738491000
    }
  }
}

Error Classes

| Class | HTTP Status | Retryable | Action | |-------|-------------|-----------|--------| | auth | 401 | No | fix_credentials | | permission | 403 | No | check_permissions | | invalid_args | 400, 422 | No | fix_arguments | | not_found | 404 | No | not_applicable | | conflict | 409 | No | not_applicable | | rate_limit | 429 | Yes | wait_and_retry | | transient | 502, 503, 504 | Yes | retry | | timeout | — | Depends | not_applicable |

Retry Rules

Read-only operations: Always retryable for rate_limit and transient
Mutations without X-Idempotency-Key: Not retryable
Mutations with X-Idempotency-Key: Retryable for rate_limit and transient

Pagination

List operations return a normalized pagination format:

{
  "data": [
    {"id": 1, "name": "repo-a"},
    {"id": 2, "name": "repo-b"}
  ],
  "pagination": {
    "has_more": true,
    "cursor": "eyJwYWdlIjoyfQ=="
  }
}

The cursor is opaque — pass it back to continue iteration until has_more is false.

Authentication

Bridge-Level (Default)

Set credentials via environment variables:

export GITHUB_TOKEN=ghp_xxxx
# or
export MCP_AUTH_TOKEN=your-token

agno-relay bridge --url http://localhost:3000

Per-Request Passthrough

Enable forwarding of Authorization header from incoming requests:

agno-relay bridge --url http://localhost:3000 --allow-auth-passthrough

Then include the header in your requests:

curl -H "Authorization: Bearer ghp_xxxx" \
  http://localhost:3847/v1/chat/completions

Mutation Warnings

Mutation tools (create, update, delete, etc.) include a warning in their description:

⚠️ Not idempotent: do not retry without verifying state. Provide X-Idempotency-Key to enable safe retries.

Trace Mode

Enable detailed request/response logging:

agno-relay bridge --url http://localhost:3000 --trace

Output shows side-by-side comparison:

═══ TRACE ═══
OpenAI Request:
  {"model":"gpt-4","messages":[...]}

MCP Request(s):
  list_repos({"org":"acme"})

MCP Response(s):
  {"items":[...],"nextPageToken":"..."}

OpenAI Response:
  {"choices":[...]}
═════════════

All sensitive values are automatically redacted.

Conformance Report

Generate a conformance report for your README:

agno-relay report