Metadata-Version: 2.4
Name: fiqros-ag-ui-crewai
Version: 0.1.0
Summary: AG-UI to CrewAI AMP FastAPI bridge
Author: Malaika Abbasi
Author-email: malaika.abbasi@fiqros.org
Requires-Python: >=3.10,<3.14
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: ag-ui-protocol (>=0.1.10)
Requires-Dist: fastapi (>=0.115.12,<0.116.0)
Requires-Dist: httpx (>=0.27,<0.29)
Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
Requires-Dist: uvicorn (>=0.34.3,<0.35.0)
Description-Content-Type: text/markdown

# 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

```bash
pip install fiqros-ag-ui-crewai
```

## Quick usage

```python
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:

```bash
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:

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

## Environment variables

When using the packaged app module:

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

## Middleware architecture

```text
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.
