> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Server: AGUI

> Deploy agents as AG-UI protocol servers for CopilotKit integration

Deploy agents as AG-UI servers for CopilotKit and other AG-UI compatible frontends.

## CLI

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonaiagents[os]"
export OPENAI_API_KEY="your-key"

# Start AGUI/A2U server
praisonai serve a2u --port 8002
```

| Option   | Default       | Description      |
| -------- | ------------- | ---------------- |
| `--host` | `127.0.0.1`   | Host to bind to  |
| `--port` | `8002`        | Server port      |
| `--file` | `agents.yaml` | Agents YAML file |

## Python

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents import AGUI
from fastapi import FastAPI
import uvicorn

agent = Agent(
    name="Assistant",
    role="Helpful AI Assistant",
    goal="Help users with their questions",
    llm="gpt-4o-mini"
)

agui = AGUI(agent=agent)

app = FastAPI()
app.include_router(agui.get_router())

uvicorn.run(app, host="0.0.0.0", port=8000)
```

**Expected Output:**

```
INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000
```

**Verify:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl http://localhost:8000/status
```

**Response:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{"status": "available"}
```

## agents.yaml

AGUI server is Python-only. No agents.yaml support.

## AGUI Endpoints

| Endpoint  | Method | Description                  |
| --------- | ------ | ---------------------------- |
| `/agui`   | POST   | Run agent with SSE streaming |
| `/status` | GET    | Check agent availability     |

## AGUI Parameters

| Parameter     | Type   | Default    | Description              |
| ------------- | ------ | ---------- | ------------------------ |
| `agent`       | Agent  | -          | PraisonAI Agent instance |
| `agents`      | Agents | -          | Multi-agent workflow     |
| `name`        | str    | agent.name | AGUI endpoint name       |
| `description` | str    | agent.role | Agent description        |
| `prefix`      | str    | `""`       | URL prefix               |

## CopilotKit Integration

```jsx theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { CopilotKit } from "@copilotkit/react-core";

function App() {
  return (
    <CopilotKit runtimeUrl="http://localhost:8000/agui">
      <YourApp />
    </CopilotKit>
  );
}
```

## Send AGUI Request

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl -X POST http://localhost:8000/agui \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "thread-123",
    "runId": "run-456",
    "state": {
      "messages": [
        {"id": "msg-1", "role": "user", "content": "Hello!"}
      ]
    }
  }'
```

**Response (SSE Stream):**

```
event: run_started
data: {"type": "run_started", "threadId": "thread-123", "runId": "run-456"}

event: text_message_start
data: {"type": "text_message_start", "messageId": "msg-2"}

event: text_message_content
data: {"type": "text_message_content", "messageId": "msg-2", "delta": "Hello! How can I help?"}

event: text_message_end
data: {"type": "text_message_end", "messageId": "msg-2"}

event: run_finished
data: {"type": "run_finished", "threadId": "thread-123", "runId": "run-456"}
```

## Event Types

| Event                  | Description               |
| ---------------------- | ------------------------- |
| `run_started`          | Agent run has started     |
| `run_finished`         | Agent run completed       |
| `run_error`            | Error occurred during run |
| `text_message_start`   | New text message started  |
| `text_message_content` | Text content delta        |
| `text_message_end`     | Text message completed    |
| `tool_call_start`      | Tool call started         |
| `tool_call_args`       | Tool call arguments       |
| `tool_call_end`        | Tool call completed       |

## JavaScript Client

```javascript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const response = await fetch('http://localhost:8000/agui', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    threadId: 'thread-123',
    runId: 'run-456',
    state: {
      messages: [{ id: 'msg-1', role: 'user', content: 'Hello!' }]
    }
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const text = decoder.decode(value);
  const lines = text.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const event = JSON.parse(line.slice(6));
      console.log('Event:', event);
    }
  }
}
```

## Troubleshooting

| Issue        | Fix                                 |
| ------------ | ----------------------------------- |
| Port in use  | `lsof -i :8000`                     |
| Missing deps | `pip install "praisonaiagents[os]"` |
| No API key   | `export OPENAI_API_KEY="your-key"`  |
| CORS errors  | Add CORS middleware to FastAPI app  |

## Related

* [AGUI API Reference](../api/agui-api) - Full AGUI endpoint documentation
* [A2A Server](./a2a) - Deploy as A2A server
* [Agents Server](./agents) - Deploy as HTTP server