FusionAGI/docs/openai_bridge.md

OpenAI Bridge for Cursor Composer

The FusionAGI OpenAI bridge exposes an OpenAI-compatible API so you can use FusionAGI's Dvādaśa multi-agent system as a custom model in Cursor Composer and other OpenAI API consumers.

Request Flow

sequenceDiagram
    participant Cursor as Cursor Composer
    participant API as FusionAGI API
    participant Orch as Orchestrator
    participant Heads as Dvādaśa Heads
    participant Witness as Witness

    Cursor->>API: POST /v1/chat/completions (messages)
    API->>Orch: submit_task(goal from messages)
    Orch->>Heads: run heads in parallel
    Heads->>Witness: head outputs
    Witness->>Orch: final_answer (synthesis)
    Orch->>API: FinalResponse
    API->>Cursor: OpenAI-format response (sync or SSE)

Overview

• GET /v1/models — Lists available models (returns fusionagi-dvadasa)
• POST /v1/chat/completions — Chat completions (sync and streaming)

The bridge translates OpenAI-style requests into FusionAGI tasks, runs the Dvādaśa heads and Witness, and returns responses in OpenAI format.

Quick Start

1. Start the FusionAGI API

# Install with API support
pip install -e ".[api]"

# Start the server (use a real LLM adapter for production)
uvicorn fusionagi.api.app:app --reload

The API runs at http://localhost:8000 by default.

2. Configure Cursor Composer

1. Open Cursor Settings → Models (or equivalent for your Cursor version).

2. Click Add Custom Model or configure an OpenAI-compatible endpoint.

3. Set:

   • Name: FusionAGI Dvādaśa
   • Base URL: http://localhost:8000/v1
   • Model ID: fusionagi-dvadasa
   • API Key: Any string (e.g. sk-fusionagi) when auth is disabled
   • Context Length: 128000 (or your preferred value)
   • Temperature: 0.7

4. Select FusionAGI as the model for Composer.

3. Use with Composer

Composer will send requests to FusionAGI. Each prompt is processed by the Dvādaśa heads (Logic, Research, Strategy, Security, Safety, etc.) and synthesized by the Witness into a single response.

Configuration

Environment variables:

Variable	Default	Description
OPENAI_BRIDGE_MODEL_ID	fusionagi-dvadasa	Model ID returned by /v1/models
OPENAI_BRIDGE_AUTH	disabled	Set to Bearer to enable API key auth
OPENAI_BRIDGE_API_KEY	(none)	Required when auth is enabled
OPENAI_BRIDGE_TIMEOUT_PER_HEAD	60	Max seconds per head agent

Authentication

Development (default): Auth is disabled. Any request is accepted.

Production: Enable Bearer auth:

export OPENAI_BRIDGE_AUTH=Bearer
export OPENAI_BRIDGE_API_KEY=your-secret-key

Cursor must then send Authorization: Bearer your-secret-key with each request.

API Details

Chat Completions

Request (sync):

{
  "model": "fusionagi-dvadasa",
  "messages": [
    {"role": "system", "content": "You are helpful."},
    {"role": "user", "content": "What is the best architecture for X?"}
  ],
  "stream": false
}

Request (streaming):

{
  "model": "fusionagi-dvadasa",
  "messages": [{"role": "user", "content": "Explain Y"}],
  "stream": true
}

Response (sync): Standard OpenAI chat completion object with choices[0].message.content and usage.

Response (streaming): Server-Sent Events (SSE) with data: lines containing OpenAI-format chunks, ending with data: [DONE].

Message Translation

The bridge converts OpenAI messages to a single prompt for Dvādaśa:

• System messages — Prepended as context
• User/assistant turns — Formatted as [User]: / [Assistant]: conversation
• Tool results — Included as [Tool name] returned: ...

Models

Request:

GET /v1/models

Response:

{
  "object": "list",
  "data": [
    {
      "id": "fusionagi-dvadasa",
      "object": "model",
      "created": 1704067200,
      "owned_by": "fusionagi"
    }
  ]
}

Limitations

• Tool calling: Not supported in v1. The bridge returns text-only responses. Cursor workflows that expect tool_calls in the model response will not work. MCP tools provided by Cursor may still be used based on model output text.
• Token counts: Usage is estimated from character counts (chars/4 heuristic). Exact token counts require a tokenizer.
• Vision/multimodal: Image content in messages is not supported.
• Latency: Dvādaśa runs multiple heads in parallel plus Witness synthesis, which can be slower than a single LLM call.

Example: curl

# List models
curl -X GET http://localhost:8000/v1/models

# Chat completion (sync)
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fusionagi-dvadasa",
    "messages": [{"role": "user", "content": "What is 2+2?"}]
  }'