feat: Introduce production-ready Flows and Crews architecture with new runner and updated documentation across multiple languages.

2026-01-25 16:18:13 +00:00 · 2025-11-30 15:29:57 -08:00
parent 2355ec0733
commit 083246aebf
8 changed files with 668 additions and 265 deletions
--- a/docs/pt-BR/concepts/production-architecture.mdx
+++ b/docs/pt-BR/concepts/production-architecture.mdx
@@ -0,0 +1,154 @@
+---
+title: Arquitetura de Produção
+description: Melhores práticas para construir aplicações de IA prontas para produção com CrewAI
+icon: server
+mode: "wide"
+---
+
+# A Mentalidade Flow-First
+
+Ao construir aplicações de IA de produção com CrewAI, **recomendamos começar com um Flow**.
+
+Embora seja possível executar Crews ou Agentes individuais, envolvê-los em um Flow fornece a estrutura necessária para uma aplicação robusta e escalável.
+
+## Por que Flows?
+
+1.  **Gerenciamento de Estado**: Flows fornecem uma maneira integrada de gerenciar o estado em diferentes etapas da sua aplicação. Isso é crucial para passar dados entre Crews, manter o contexto e lidar com entradas do usuário.
+2.  **Controle**: Flows permitem definir caminhos de execução precisos, incluindo loops, condicionais e lógica de ramificação. Isso é essencial para lidar com casos extremos e garantir que sua aplicação se comporte de maneira previsível.
+3.  **Observabilidade**: Flows fornecem uma estrutura clara que facilita o rastreamento da execução, a depuração de problemas e o monitoramento do desempenho. Recomendamos o uso do [CrewAI Tracing](/pt-BR/observability/tracing) para insights detalhados. Basta executar `crewai login` para habilitar recursos de observabilidade gratuitos.
+
+## A Arquitetura
+
+Uma aplicação CrewAI de produção típica se parece com isso:
+
+```mermaid
+graph TD
+    Start((Início)) --> Flow[Orquestrador de Flow]
+    Flow --> State{Gerenciamento de Estado}
+    State --> Step1[Etapa 1: Coleta de Dados]
+    Step1 --> Crew1[Crew de Pesquisa]
+    Crew1 --> State
+    State --> Step2{Verificação de Condição}
+    Step2 -- "Válido" --> Step3[Etapa 3: Execução]
+    Step3 --> Crew2[Crew de Ação]
+    Step2 -- "Inválido" --> End((Fim))
+    Crew2 --> End
+```
+
+### 1. A Classe Flow
+Sua classe `Flow` é o ponto de entrada. Ela define o esquema de estado e os métodos que executam sua lógica.
+
+```python
+from crewai.flow.flow import Flow, listen, start
+from pydantic import BaseModel
+
+class AppState(BaseModel):
+    user_input: str = ""
+    research_results: str = ""
+    final_report: str = ""
+
+class ProductionFlow(Flow[AppState]):
+    @start()
+    def gather_input(self):
+        # ... lógica para obter entrada ...
+        pass
+
+    @listen(gather_input)
+    def run_research_crew(self):
+        # ... acionar um Crew ...
+        pass
+```
+
+### 2. Gerenciamento de Estado
+Use modelos Pydantic para definir seu estado. Isso garante a segurança de tipos e deixa claro quais dados estão disponíveis em cada etapa.
+
+- **Mantenha o mínimo**: Armazene apenas o que você precisa persistir entre as etapas.
+- **Use dados estruturados**: Evite dicionários não estruturados quando possível.
+
+### 3. Crews como Unidades de Trabalho
+Delegue tarefas complexas para Crews. Um Crew deve ser focado em um objetivo específico (por exemplo, "Pesquisar um tópico", "Escrever uma postagem no blog").
+
+- **Não superengendre Crews**: Mantenha-os focados.
+- **Passe o estado explicitamente**: Passe os dados necessários do estado do Flow para as entradas do Crew.
+
+```python
+    @listen(gather_input)
+    def run_research_crew(self):
+        crew = ResearchCrew()
+        result = crew.kickoff(inputs={"topic": self.state.user_input})
+        self.state.research_results = result.raw
+```
+
+## Primitivas de Controle
+
+Aproveite as primitivas de controle do CrewAI para adicionar robustez e controle aos seus Crews.
+
+### 1. Task Guardrails
+Use [Task Guardrails](/pt-BR/concepts/tasks#task-guardrails) para validar as saídas das tarefas antes que sejam aceitas. Isso garante que seus agentes produzam resultados de alta qualidade.
+
+```python
+def validate_content(result: TaskOutput) -> Tuple[bool, Any]:
+    if len(result.raw) < 100:
+        return (False, "Content is too short. Please expand.")
+    return (True, result.raw)
+
+task = Task(
+    ...,
+    guardrail=validate_content
+)
+```
+
+### 2. Saídas Estruturadas
+Sempre use saídas estruturadas (`output_pydantic` ou `output_json`) ao passar dados entre tarefas ou para sua aplicação. Isso evita erros de análise e garante a segurança de tipos.
+
+```python
+class ResearchResult(BaseModel):
+    summary: str
+    sources: List[str]
+
+task = Task(
+    ...,
+    output_pydantic=ResearchResult
+)
+```
+
+### 3. LLM Hooks
+Use [LLM Hooks](/pt-BR/learn/llm-hooks) para inspecionar ou modificar mensagens antes que elas sejam enviadas para o LLM, ou para higienizar respostas.
+
+```python
+@before_llm_call
+def log_request(context):
+    print(f"Agent {context.agent.role} is calling the LLM...")
+```
+
+## Padrões de Implantação
+
+Ao implantar seu Flow, considere o seguinte:
+
+### CrewAI Enterprise
+A maneira mais fácil de implantar seu Flow é usando o CrewAI Enterprise. Ele lida com a infraestrutura, autenticação e monitoramento para você.
+
+Confira o [Guia de Implantação](/pt-BR/enterprise/guides/deploy-crew) para começar.
+
+```bash
+crewai deploy create
+```
+
+### Execução Assíncrona
+Para tarefas de longa duração, use `kickoff_async` para evitar bloquear sua API.
+
+### Persistência
+Use o decorador `@persist` para salvar o estado do seu Flow em um banco de dados. Isso permite retomar a execução se o processo falhar ou se você precisar esperar pela entrada humana.
+
+```python
+@persist
+class ProductionFlow(Flow[AppState]):
+    # ...
+```
+
+## Resumo
+
+- **Comece com um Flow.**
+- **Defina um Estado claro.**
+- **Use Crews para tarefas complexas.**
+- **Implante com uma API e persistência.**
--- a/docs/pt-BR/introduction.mdx
+++ b/docs/pt-BR/introduction.mdx
@@ -7,110 +7,89 @@ mode: "wide"

 # O que é CrewAI?

-**CrewAI é um framework Python enxuto e ultrarrápido, construído totalmente do zero—completamente independente do LangChain ou de outros frameworks de agentes.**
+**CrewAI é o principal framework open-source para orquestrar agentes de IA autônomos e construir fluxos de trabalho complexos.**

-O CrewAI capacita desenvolvedores tanto com simplicidade de alto nível quanto com controle detalhado de baixo nível, ideal para criar agentes de IA autônomos sob medida para qualquer cenário:
+Ele capacita desenvolvedores a construir sistemas multi-agente prontos para produção, combinando a inteligência colaborativa dos **Crews** com o controle preciso dos **Flows**.

- **[Crews do CrewAI](/pt-BR/guides/crews/first-crew)**: Otimizados para autonomia e inteligência colaborativa, permitindo criar equipes de IA onde cada agente possui funções, ferramentas e objetivos específicos.
- **[Flows do CrewAI](/pt-BR/guides/flows/first-flow)**: Proporcionam controle granular, orientado por eventos, com chamadas LLM individuais para uma orquestração precisa das tarefas, além de suportar Crews nativamente.
+- **[Flows do CrewAI](/pt-BR/guides/flows/first-flow)**: A espinha dorsal da sua aplicação de IA. Flows permitem criar fluxos de trabalho estruturados e orientados a eventos que gerenciam estado e controlam a execução. Eles fornecem a estrutura para seus agentes de IA trabalharem.
+- **[Crews do CrewAI](/pt-BR/guides/crews/first-crew)**: As unidades de trabalho dentro do seu Flow. Crews são equipes de agentes autônomos que colaboram para resolver tarefas específicas delegadas a eles pelo Flow.

-Com mais de 100.000 desenvolvedores certificados em nossos cursos comunitários, o CrewAI está se tornando rapidamente o padrão para automação de IA pronta para empresas.
+Com mais de 100.000 desenvolvedores certificados em nossos cursos comunitários, o CrewAI é o padrão para automação de IA pronta para empresas.

+## A Arquitetura do CrewAI

-## Como funcionam os Crews
+A arquitetura do CrewAI foi projetada para equilibrar autonomia com controle.
+
+### 1. Flows: A Espinha Dorsal

 <Note>
-  Assim como uma empresa possui departamentos (Vendas, Engenharia, Marketing) trabalhando juntos sob uma liderança para atingir objetivos de negócio, o CrewAI ajuda você a criar uma “organização” de agentes de IA com funções especializadas colaborando para realizar tarefas complexas.
-</Note>
-
-<Frame caption="Visão Geral do Framework CrewAI">
-  <img src="/images/crews.png" alt="Visão Geral do Framework CrewAI" />
-</Frame>
-
-| Componente | Descrição | Principais Funcionalidades |
-|:-----------|:-----------:|:-------------------------|
-| **Crew** | Organização de mais alto nível | • Gerencia equipes de agentes de IA<br/>• Supervisiona fluxos de trabalho<br/>• Garante colaboração<br/>• Entrega resultados |
-| **Agentes de IA** | Membros especializados da equipe | • Possuem funções específicas (pesquisador, escritor)<br/>• Utilizam ferramentas designadas<br/>• Podem delegar tarefas<br/>• Tomam decisões autônomas |
-| **Process** | Sistema de gestão do fluxo de trabalho | • Define padrões de colaboração<br/>• Controla designação de tarefas<br/>• Gerencia interações<br/>• Garante execução eficiente |
-| **Tasks** | Atribuições individuais | • Objetivos claros<br/>• Utilizam ferramentas específicas<br/>• Alimentam processos maiores<br/>• Geram resultados acionáveis |
-
-### Como tudo trabalha junto
-
-1. O **Crew** organiza toda a operação
-2. **Agentes de IA** realizam tarefas especializadas
-3. O **Process** garante colaboração fluida
-4. **Tasks** são concluídas para alcançar o objetivo
-
-## Principais Funcionalidades
-
-<CardGroup cols={2}>
-  <Card title="Agentes Baseados em Funções" icon="users">
-    Crie agentes especializados com funções, conhecimentos e objetivos definidos – de pesquisadores e analistas a escritores
-  </Card>
-  <Card title="Ferramentas Flexíveis" icon="screwdriver-wrench">
-    Equipe os agentes com ferramentas e APIs personalizadas para interagir com serviços e fontes de dados externas
-  </Card>
-  <Card title="Colaboração Inteligente" icon="people-arrows">
-    Agentes trabalham juntos, compartilhando insights e coordenando tarefas para conquistar objetivos complexos
-  </Card>
-  <Card title="Gerenciamento de Tarefas" icon="list-check">
-    Defina fluxos de trabalho sequenciais ou paralelos, com agentes lidando automaticamente com dependências entre tarefas
-  </Card>
-</CardGroup>
-
-## Como funcionam os Flows
-
-<Note>
-  Enquanto Crews se destacam na colaboração autônoma, Flows proporcionam automações estruturadas, oferecendo controle granular sobre a execução dos fluxos de trabalho. Flows garantem execução confiável, segura e eficiente, lidando com lógica condicional, loops e gerenciamento dinâmico de estados com precisão. Flows se integram perfeitamente com Crews, permitindo equilibrar alta autonomia com controle rigoroso.
+  Pense em um Flow como o "gerente" ou a "definição do processo" da sua aplicação. Ele define as etapas, a lógica e como os dados se movem através do seu sistema.
 </Note>

 <Frame caption="Visão Geral do Framework CrewAI">
  <img src="/images/flows.png" alt="Visão Geral do Framework CrewAI" />
 </Frame>

-| Componente | Descrição | Principais Funcionalidades |
-|:-----------|:-----------:|:-------------------------|
-| **Flow** | Orquestração de fluxo de trabalho estruturada | • Gerencia caminhos de execução<br/>• Lida com transições de estado<br/>• Controla a sequência de tarefas<br/>• Garante execução confiável |
-| **Events** | Gatilhos para ações nos fluxos | • Iniciam processos específicos<br/>• Permitem respostas dinâmicas<br/>• Suportam ramificações condicionais<br/>• Adaptam-se em tempo real |
-| **States** | Contextos de execução dos fluxos | • Mantêm dados de execução<br/>• Permitem persistência<br/>• Suportam retomada<br/>• Garantem integridade na execução |
-| **Crew Support** | Aprimora automação de fluxos | • Injeta autonomia quando necessário<br/>• Complementa fluxos estruturados<br/>• Equilibra automação e inteligência<br/>• Permite tomada de decisão adaptativa |
+Flows fornecem:
+- **Gerenciamento de Estado**: Persistem dados através de etapas e execuções.
+- **Execução Orientada a Eventos**: Acionam ações com base em eventos ou entradas externas.
+- **Controle de Fluxo**: Usam lógica condicional, loops e ramificações.

-### Capacidades-Chave
+### 2. Crews: A Inteligência
+
+<Note>
+  Crews são as "equipes" que fazem o trabalho pesado. Dentro de um Flow, você pode acionar um Crew para lidar com um problema complexo que requer criatividade e colaboração.
+</Note>
+
+<Frame caption="Visão Geral do Framework CrewAI">
+  <img src="/images/crews.png" alt="Visão Geral do Framework CrewAI" />
+</Frame>
+
+Crews fornecem:
+- **Agentes com Funções**: Agentes especializados com objetivos e ferramentas específicas.
+- **Colaboração Autônoma**: Agentes trabalham juntos para resolver tarefas.
+- **Delegação de Tarefas**: Tarefas são atribuídas e executadas com base nas capacidades dos agentes.
+
+## Como Tudo Funciona Junto
+
+1.  **O Flow** aciona um evento ou inicia um processo.
+2.  **O Flow** gerencia o estado e decide o que fazer a seguir.
+3.  **O Flow** delega uma tarefa complexa para um **Crew**.
+4.  Os agentes do **Crew** colaboram para completar a tarefa.
+5.  **O Crew** retorna o resultado para o **Flow**.
+6.  **O Flow** continua a execução com base no resultado.
+
+## Principais Funcionalidades

 <CardGroup cols={2}>
-  <Card title="Orquestração Orientada por Eventos" icon="bolt">
-    Defina caminhos de execução precisos respondendo dinamicamente a eventos
+  <Card title="Flows de Nível de Produção" icon="arrow-progress">
+    Construa fluxos de trabalho confiáveis e com estado que podem lidar com processos de longa duração e lógica complexa.
  </Card>
-  <Card title="Controle Detalhado" icon="sliders">
-    Gerencie estados de fluxo de trabalho e execução condicional de forma segura e eficiente
+  <Card title="Crews Autônomos" icon="users">
+    Implante equipes de agentes que podem planejar, executar e colaborar para alcançar objetivos de alto nível.
  </Card>
-  <Card title="Integração Nativa com Crew" icon="puzzle-piece">
-    Combine de forma simples com Crews para maior autonomia e inteligência
+  <Card title="Ferramentas Flexíveis" icon="screwdriver-wrench">
+     Conecte seus agentes a qualquer API, banco de dados ou ferramenta local.
  </Card>
-  <Card title="Execução Determinística" icon="route">
-    Garanta resultados previsíveis com controle explícito de fluxo e tratamento de erros
+  <Card title="Segurança Empresarial" icon="lock">
+    Projetado com segurança e conformidade em mente para implantações empresariais.
  </Card>
 </CardGroup>

-## Quando usar Crews versus Flows
+## Quando usar Crews vs. Flows

-<Note>
-  Entender quando utilizar [Crews](/pt-BR/guides/crews/first-crew) ou [Flows](/pt-BR/guides/flows/first-flow) é fundamental para maximizar o potencial do CrewAI em suas aplicações.
-</Note>
+**A resposta curta: Use ambos.**

-| Caso de uso | Abordagem recomendada | Por quê? |
-|:------------|:---------------------|:---------|
-| **Pesquisa aberta** | [Crews](/pt-BR/guides/crews/first-crew) | Quando as tarefas exigem criatividade, exploração e adaptação |
-| **Geração de conteúdo** | [Crews](/pt-BR/guides/crews/first-crew) | Para criação colaborativa de artigos, relatórios ou materiais de marketing |
-| **Fluxos de decisão** | [Flows](/pt-BR/guides/flows/first-flow) | Quando é necessário caminhos de decisão previsíveis, auditáveis e com controle preciso |
-| **Orquestração de APIs** | [Flows](/pt-BR/guides/flows/first-flow) | Para integração confiável com múltiplos serviços externos em sequência específica |
-| **Aplicações híbridas** | Abordagem combinada | Use [Flows](/pt-BR/guides/flows/first-flow) para orquestrar o processo geral com [Crews](/pt-BR/guides/crews/first-crew) lidando com subtarefas complexas |
+Para qualquer aplicação pronta para produção, **comece com um Flow**.

-### Framework de Decisão
+- **Use um Flow** para definir a estrutura geral, estado e lógica da sua aplicação.
+- **Use um Crew** dentro de uma etapa do Flow quando precisar de uma equipe de agentes para realizar uma tarefa específica e complexa que requer autonomia.

- **Escolha [Crews](/pt-BR/guides/crews/first-crew) quando:** Precisa de resolução autônoma de problemas, colaboração criativa ou tarefas exploratórias
- **Escolha [Flows](/pt-BR/guides/flows/first-flow) quando:** Requer resultados determinísticos, auditabilidade ou controle preciso sobre a execução
- **Combine ambos quando:** Sua aplicação precisa de processos estruturados e também de bolsões de inteligência autônoma
+| Caso de Uso | Arquitetura |
+| :--- | :--- |
+| **Automação Simples** | Flow único com tarefas Python |
+| **Pesquisa Complexa** | Flow gerenciando estado -> Crew realizando pesquisa |
+| **Backend de Aplicação** | Flow lidando com requisições API -> Crew gerando conteúdo -> Flow salvando no BD |

 ## Por que escolher o CrewAI?

@@ -124,13 +103,6 @@ Com mais de 100.000 desenvolvedores certificados em nossos cursos comunitários,
 ## Pronto para começar a construir?

 <CardGroup cols={2}>
-  <Card
-    title="Crie Seu Primeiro Crew"
-    icon="users-gear"
-    href="/pt-BR/guides/crews/first-crew"
-  >
-    Tutorial passo a passo para criar uma equipe de IA colaborativa que trabalha junto para resolver problemas complexos.
-  </Card>
  <Card
    title="Crie Seu Primeiro Flow"
    icon="diagram-project"
@@ -138,6 +110,13 @@ Com mais de 100.000 desenvolvedores certificados em nossos cursos comunitários,
  >
    Aprenda a criar fluxos de trabalho estruturados e orientados por eventos com controle preciso de execução.
  </Card>
+  <Card
+    title="Crie Seu Primeiro Crew"
+    icon="users-gear"
+    href="/pt-BR/guides/crews/first-crew"
+  >
+    Tutorial passo a passo para criar uma equipe de IA colaborativa que trabalha junto para resolver problemas complexos.
+  </Card>
 </CardGroup>

 <CardGroup cols={3}>