Frontend Overview

Dê uma interface de usuário aos seus agentes

O CrewAI executa seus agentes. O CopilotKit 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. 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

Renderize as chamadas de tool e o estado do agente como seus próprios componentes React.

Human-in-the-Loop

Pause o agente para coletar aprovação ou input do usuário no meio da execução.

Shared State

Mantenha o estado do agente e a UI do seu app em sincronia bidirecional.

Channels

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:

CrewAI agent server — um processo Python que serve o seu Crew ou Flow por AG-UI (FastAPI + ag-ui-crewai).
CopilotKit runtime — uma rota Next.js que registra o seu agente e faz o proxy das requisições para ele.
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

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

O CrewAI roda por trás do AG-UI em três formatos: Flows comuns (usados ao longo destes guias), Conversational Flows (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

Sirva seu agente por AG-UI

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

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.

# 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",
)

# 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:

uvicorn server:app --port 8000

Defina as variáveis de ambiente do seu provedor de LLM (por exemplo OPENAI_API_KEY) antes de iniciar o servidor.

Crie um app Next.js

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

npx create-next-app@latest my-app
cd my-app

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

npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/crewai

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.

// 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;

Envolva seu app com o provider

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

// 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>
  );
}

Execute

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

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.

import { CopilotSidebar } from "@copilotkit/react-core/v2";

<CopilotSidebar agentId="recipe" />

import { CopilotPopup } from "@copilotkit/react-core/v2";

<CopilotPopup agentId="recipe" />

import { CopilotChat } from "@copilotkit/react-core/v2";

<CopilotChat agentId="recipe" />

Para onde ir em seguida

Generative UI

Renderize chamadas de tool e o estado do agente como componentes personalizados.

Frontend Actions

Permita que o agente chame funções que rodam no navegador.

Human-in-the-Loop

Restrinja ações do agente por trás da aprovação do usuário.

Predictive State

Transmita o estado em andamento para a UI enquanto o agente trabalha.

Começando

Guias

Conceitos-Chave

Integração MCP

Ferramentas

Observabilidade

Aprenda

Telemetria

Frontend Overview

Dê uma interface de usuário aos seus agentes

Generative UI

Human-in-the-Loop

Shared State

Channels

Arquitetura

Guia de integração

Opções de UI de chat

Para onde ir em seguida

Generative UI

Frontend Actions

Human-in-the-Loop

Predictive State

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

Generative UI

Human-in-the-Loop

Shared State

Channels

​Arquitetura

​Guia de integração

​Opções de UI de chat

​Para onde ir em seguida

Generative UI

Frontend Actions

Human-in-the-Loop

Predictive State

Dê uma interface de usuário aos seus agentes

Arquitetura

Guia de integração

Opções de UI de chat

Para onde ir em seguida