fiqros-ag-ui-crewai

fiqros-ag-ui-crewai is a FastAPI bridge that converts CrewAI AMP REST responses into AG-UI event streams (SSE), so AG-UI clients (including CopilotKit Cloud) can consume Crew runs correctly.

It acts as middleware between:

• CopilotKit Cloud / AG-UI client (expects AG-UI streaming events)
• CrewAI AMP deployment (exposes REST endpoints like /kickoff and /status/{id})

Without this bridge, pointing CopilotKit directly to an AMP URL typically fails because AMP does not emit AG-UI terminal events on the wire.

What this package does

The bridge helper (add_crewai_amp_fastapi_endpoint) mounts a FastAPI route that:

1. Accepts AG-UI RunAgentInput over POST (for example, /agent)
2. Emits RUN_STARTED
3. Calls CrewAI AMP POST /kickoff with the latest user message
4. Polls AMP GET /status/{kickoff_id} until terminal state
5. On success:
   • emits TEXT_MESSAGE_START
   • emits chunked TEXT_MESSAGE_CONTENT deltas
   • emits TEXT_MESSAGE_END
6. On failure:
   • emits RUN_ERROR
7. Always emits RUN_FINISHED (required so AG-UI clients do not hang)

Why this works with AG-UI

AG-UI clients expect a protocol-compliant event stream, including terminal events. This package converts AMP JSON status/result payloads into AG-UI-compatible SSE events, making CrewAI AMP flows consumable by AG-UI runtimes.

Installation

pip install fiqros-ag-ui-crewai

Quick usage

from fastapi import FastAPI
from fiqros_ag_ui_crewai.amp import add_crewai_amp_fastapi_endpoint

app = FastAPI(title="AG-UI <-> CrewAI AMP Bridge")

add_crewai_amp_fastapi_endpoint(
    app,
    deployment_url="https://your-deployment.crewai.com",
    bearer_token="your-crewai-bearer-token",
    path="/agent",
)

Run:

uvicorn your_module:app --host 0.0.0.0 --port 8000

Then register your AG-UI endpoint as:

• http://localhost:8000/agent (local)
• https://<your-ngrok-domain>/agent (public tunnel)

Optional packaged app entry

This package includes fiqros_ag_ui_crewai.app with a ready-made app object that reads environment variables:

• CREWAI_DEPLOYMENT_URL
• CREWAI_BEARER_TOKEN

Run it directly:

uvicorn fiqros_ag_ui_crewai.app:app --host 0.0.0.0 --port 8000

Environment variables

When using the packaged app module:

CREWAI_DEPLOYMENT_URL=https://your-deployment.crewai.com
CREWAI_BEARER_TOKEN=your-token

Middleware architecture

CopilotKit Cloud / AG-UI client
            |
            |  POST /agent (AG-UI input)
            v
     FastAPI bridge (this package)
            |
            |  POST /kickoff
            |  GET  /status/{kickoff_id} (polling)
            v
      CrewAI AMP deployment
            |
            |  JSON status/result
            v
     Bridge converts JSON -> AG-UI SSE events
            |
            v
CopilotKit Cloud / AG-UI client

Tuning parameters

add_crewai_amp_fastapi_endpoint(...) supports:

• path (default: /)
• poll_interval_seconds (default: 2.0)
• kickoff_timeout_seconds (default: 600.0)
• chunk_size (default: 64)

These control endpoint mount path, AMP polling cadence, timeout ceiling, and response chunking granularity.

Notes

• Use path="/agent" to avoid route collisions and to match typical AG-UI agent endpoint conventions.
• Ensure your client points to /agent (not /) if mounted there.
• Keep your bearer token server-side only; never expose it in frontend code.