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

# Frontend Overview

> Construa interfaces de usuário interativas para seus agentes CrewAI com o CopilotKit e o protocolo AG-UI.

## Dê uma interface de usuário aos seus agentes

O CrewAI executa seus agentes. O [CopilotKit](https://copilotkit.ai) dá a eles um frontend. Juntos, eles permitem que você construa aplicações em que os usuários conversam com um Crew ou Flow, o observam trabalhar em tempo real, aprovam suas decisões e veem sua saída renderizada como UI ao vivo, em vez de paredes de texto.

Os dois se conectam através do [protocolo AG-UI](https://docs.ag-ui.com). O pacote `ag-ui-crewai` expõe qualquer Crew ou Flow como um endpoint AG-UI. Os hooks e componentes React do CopilotKit consomem esse endpoint. Isso desbloqueia experiências que vão muito além de uma caixa de chat:

> **[Generative UI](https://docs.crewai.com/edge/en/guides/frontend/generative-ui.md)**
>
> Renderize as chamadas de tool e o estado do agente como seus próprios componentes React.

> **[Human-in-the-Loop](https://docs.crewai.com/edge/en/guides/frontend/human-in-the-loop.md)**
>
> Pause o agente para coletar aprovação ou input do usuário no meio da execução.

> **[Shared State](https://docs.crewai.com/edge/en/guides/frontend/shared-state.md)**
>
> Mantenha o estado do agente e a UI do seu app em sincronia bidirecional.

> **[Channels](https://docs.crewai.com/edge/pt-BR/guides/frontend/channels.md)**
>
> Execute o mesmo agente como um bot do Slack, Discord ou Teams.

Este guia coloca um Crew ou Flow conversando com um frontend Next.js de ponta a ponta. O restante da seção se apoia no app que você configura aqui.

## Arquitetura

Há três peças:

1. **CrewAI agent server** — um processo Python que serve o seu Crew ou Flow por AG-UI (FastAPI + `ag-ui-crewai`).
2. **CopilotKit runtime** — uma rota Next.js que registra o seu agente e faz o proxy das requisições para ele.
3. **React frontend** — o provider `<CopilotKit>` mais os componentes de chat e de generative UI.

```
React app  ──►  CopilotKit runtime (/api/copilotkit)  ──►  CrewAI server (AG-UI)  ──►  Crew / Flow
```

> [!NOTE]
>
> Este guia cobre o caminho **self-hosted**: você mesmo executa o servidor do agente CrewAI com `ag-ui-crewai`, e ele funciona localmente sem nenhum serviço gerenciado. O CopilotKit também oferece um caminho **gerenciado** (CopilotKit Cloud / Enterprise Intelligence) com threads hospedadas e um inspetor — consulte o [quickstart de CrewAI do CopilotKit](https://docs.copilotkit.ai/crewai-crews/quickstart) se preferir isso. O código do frontend nesta seção é o mesmo de qualquer forma; apenas como o agente é hospedado e registrado é que muda.

> [!NOTE]
>
> O CrewAI roda por trás do AG-UI em três formatos: **Flows** comuns (usados ao longo destes guias), **[Conversational Flows](https://docs.crewai.com/edge/en/guides/frontend/conversational-flows.md)** (nativos, cientes de sessão, baseados em turnos, com paridade total de recursos) e **Crews** (chat básico). O frontend nesta seção é idêntico entre eles — apenas a autoria e o registro no backend é que diferem.

## Guia de integração

**1. Sirva seu agente por AG-UI**

Instale o pacote de integração no seu projeto CrewAI:

```bash theme={null}
pip install ag-ui-crewai
```

Exponha o seu agente a partir de um app FastAPI. Flows usam `add_crewai_flow_fastapi_endpoint`; Crews usam `add_crewai_crew_fastapi_endpoint`. Você pode registrar quantos quiser, cada um em seu próprio path.

```python Flow theme={null}
# server.py
from fastapi import FastAPI
from ag_ui_crewai.endpoint import add_crewai_flow_fastapi_endpoint
from my_agents.recipe_flow import RecipeFlow

app = FastAPI(title="CrewAI Agent Server")

add_crewai_flow_fastapi_endpoint(
    app=app,
    flow=RecipeFlow(),
    path="/recipe",
)
```

```python Crew theme={null}
# server.py
from fastapi import FastAPI
from ag_ui_crewai.endpoint import add_crewai_crew_fastapi_endpoint
from my_agents.research_crew import ResearchCrew

app = FastAPI(title="CrewAI Agent Server")

add_crewai_crew_fastapi_endpoint(
    app=app,
    crew=ResearchCrew().crew(),
    path="/research",
)
```

Execute:

```bash theme={null}
uvicorn server:app --port 8000
```

> [!NOTE]
>
> Defina as variáveis de ambiente do seu provedor de LLM (por exemplo `OPENAI_API_KEY`) antes de iniciar o servidor.

**2. Crie um app Next.js**

Se você ainda não tem um frontend, gere um:

```bash theme={null}
npx create-next-app@latest my-app
cd my-app
```

Instale o CopilotKit e o cliente AG-UI do CrewAI:

```bash theme={null}
npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/crewai
```

**3. Adicione o runtime do CopilotKit**

Crie uma rota que registre o(s) seu(s) agente(s) CrewAI no runtime do CopilotKit. Cada agente aponta para um path no seu servidor Python via `CrewAIAgent`.

```ts theme={null}
// app/api/copilotkit/route.ts
import {
  CopilotRuntime,
  InMemoryAgentRunner,
  createCopilotEndpoint,
} from "@copilotkit/runtime/v2";
import { CrewAIAgent } from "@ag-ui/crewai";
import { handle } from "hono/vercel";

const runtime = new CopilotRuntime({
  agents: {
    recipe: new CrewAIAgent({ url: "http://localhost:8000/recipe" }),
  },
  runner: new InMemoryAgentRunner(),
});

const app = createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
});

const handler = handle(app);
export const GET = handler;
export const POST = handler;
```

**4. Envolva seu app com o provider**

Aponte `<CopilotKit>` para a rota do runtime e nomeie o agente que você registrou.

```tsx theme={null}
// app/page.tsx
"use client";
import { CopilotKit } from "@copilotkit/react-core";
import { CopilotSidebar } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

export default function Page() {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit" agent="recipe">
      <YourApp />
      <CopilotSidebar agentId="recipe" labels={{ modalHeaderTitle: "Assistant" }} />
    </CopilotKit>
  );
}
```

**5. Execute**

Inicie os dois processos e abra o app. Conversar na sidebar agora executa o seu Crew ou Flow.

```bash theme={null}
uvicorn server:app --port 8000   # terminal 1
npm run dev                       # terminal 2
```

## Opções de UI de chat

O CopilotKit entrega três superfícies de chat intercambiáveis. Troque o componente; a fiação é idêntica.

```tsx Sidebar theme={null}
import { CopilotSidebar } from "@copilotkit/react-core/v2";

<CopilotSidebar agentId="recipe" />
```

```tsx Popup theme={null}
import { CopilotPopup } from "@copilotkit/react-core/v2";

<CopilotPopup agentId="recipe" />
```

```tsx Inline theme={null}
import { CopilotChat } from "@copilotkit/react-core/v2";

<CopilotChat agentId="recipe" />
```

## Para onde ir em seguida

> **[Generative UI](https://docs.crewai.com/edge/en/guides/frontend/generative-ui.md)**
>
> Renderize chamadas de tool e o estado do agente como componentes personalizados.

> **[Frontend Actions](https://docs.crewai.com/edge/en/guides/frontend/frontend-actions.md)**
>
> Permita que o agente chame funções que rodam no navegador.

> **[Human-in-the-Loop](https://docs.crewai.com/edge/en/guides/frontend/human-in-the-loop.md)**
>
> Restrinja ações do agente por trás da aprovação do usuário.

> **[Predictive State](https://docs.crewai.com/edge/en/guides/frontend/predictive-state-updates.md)**
>
> Transmita o estado em andamento para a UI enquanto o agente trabalha.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.