Add pt-BR docs translation (#3039)

* docs: add pt-br translations

Powered by a CrewAI Flow https://github.com/danielfsbarreto/docs_translator

* Update mcp/overview.mdx brazilian docs

Its en-US counterpart was updated after I did a pass,
so now it includes the new section about @CrewBase

docs/pt-BR/guides/flows/mastering-flow-state.mdx

@@ -0,0 +1,294 @@
+---
+title: Dominando o Gerenciamento de Estado em Flows
+description: Um guia abrangente sobre como gerenciar, persistir e utilizar o estado em CrewAI Flows para construir aplicações de IA robustas.
+icon: diagram-project
+---
+
+## Entendendo o Poder do Estado em Flows
+
+O gerenciamento de estado é a espinha dorsal de qualquer workflow de IA sofisticado. Nos Flows da CrewAI, o sistema de estado permite manter o contexto, compartilhar dados entre etapas e construir lógicas de aplicação complexas. Dominar o gerenciamento de estado é essencial para criar aplicações de IA confiáveis, sustentáveis e poderosas.
+
+Este guia vai te levar por tudo o que você precisa saber sobre como gerenciar o estado em CrewAI Flows, desde conceitos básicos até técnicas avançadas, com exemplos práticos de código ao longo do conteúdo.
+
+### Por Que o Gerenciamento de Estado Importa
+
+Um gerenciamento de estado efetivo possibilita que você:
+
+1. **Mantenha o contexto entre as etapas de execução** – Transfira informações de forma transparente entre diferentes estágios do seu workflow
+2. **Construa lógicas condicionais complexas** – Tome decisões baseadas nos dados acumulados
+3. **Crie aplicações persistentes** – Salve e recupere o progresso do workflow
+4. **Trate erros de forma elegante** – Implemente padrões de recuperação para aplicações mais robustas
+5. **Escalone suas aplicações** – Ofereça suporte a workflows complexos com organização apropriada dos dados
+6. **Habilite aplicações conversacionais** – Armazene e acesse o histórico da conversa para interações de IA com contexto
+
+Vamos explorar como aproveitar essas capacidades de forma eficiente.
+
+## Fundamentos do Gerenciamento de Estado
+
+### O Ciclo de Vida do Estado em um Flow
+
+Nos Flows da CrewAI, o estado segue um ciclo de vida previsível:
+
+1. **Inicialização** – Quando um flow é criado, seu estado é inicializado (como um dicionário vazio ou uma instância de modelo Pydantic)
+2. **Modificação** – Os métodos do flow acessam e modificam o estado durante a execução
+3. **Transmissão** – O estado é automaticamente passado entre os métodos do flow
+4. **Persistência** (opcional) – O estado pode ser salvo em um armazenamento e recuperado posteriormente
+5. **Conclusão** – O estado final reflete as mudanças acumuladas de todos os métodos executados
+
+Compreender esse ciclo de vida é crucial para projetar flows eficientes.
+
+### Duas Abordagens Para Gerenciar Estado
+
+A CrewAI oferece duas maneiras para você gerenciar o estado nos seus flows:
+
+1. **Estado Não Estruturado** – Usando objetos do tipo dicionário para mais flexibilidade
+2. **Estado Estruturado** – Usando modelos Pydantic para segurança de tipo e validação
+
+Vamos analisar cada abordagem em detalhe.
+
+## Gerenciamento de Estado Não Estruturado
+
+O estado não estruturado utiliza uma abordagem semelhante a dicionários, oferecendo flexibilidade e simplicidade para aplicações diretas.
+
+### Como Funciona
+
+Com estado não estruturado:
+- Você acessa o estado via `self.state`, que se comporta como um dicionário
+- Pode adicionar, modificar ou remover chaves livremente a qualquer momento
+- Todo o estado está disponível automaticamente para todos os métodos do flow
+
+### Exemplo Básico
+
+Veja um exemplo simples de gerenciamento de estado não estruturado:
+
+```python
+# código não traduzido
+```
+
+### Quando Usar Estado Não Estruturado
+
+O estado não estruturado é ideal para:
+- Prototipagem rápida e flows simples
+- Necessidade de estado que evolui dinamicamente
+- Casos onde a estrutura pode não ser conhecida antecipadamente
+- Flows com requisitos de estado simples
+
+Embora seja flexível, o estado não estruturado não possui checagem de tipos nem validação de esquema, o que pode gerar erros em aplicações mais complexas.
+
+## Gerenciamento de Estado Estruturado
+
+O estado estruturado utiliza modelos Pydantic para definir um esquema para o estado do seu flow, provendo segurança de tipo, validação e melhor experiência de desenvolvimento.
+
+### Como Funciona
+
+Ao utilizar estado estruturado:
+- Você define um modelo Pydantic que representa a estrutura do seu estado
+- Passa este tipo de modelo para sua classe Flow como parâmetro de tipo
+- Acessa o estado via `self.state`, que se comporta como uma instância do modelo Pydantic
+- Todos os campos são validados de acordo com os tipos definidos
+- O IDE oferece autocompletar e suporte à checagem de tipos
+
+### Exemplo Básico
+
+Veja como implementar o gerenciamento de estado estruturado:
+
+```python
+# código não traduzido
+```
+
+### Benefícios do Estado Estruturado
+
+Utilizar estado estruturado traz várias vantagens:
+
+1. **Segurança de Tipo** – Detecte erros de tipo durante o desenvolvimento
+2. **Autodocumentação** – O modelo de estado documenta claramente quais dados estão disponíveis
+3. **Validação** – Validação automática de tipos de dados e restrições
+4. **Suporte do IDE** – Obtenha autocompletar e documentação inline
+5. **Valores Padrão** – Defina facilmente valores padrões para falta de dados
+
+### Quando Usar Estado Estruturado
+
+O estado estruturado é recomendado para:
+- Flows complexos com esquemas de dados bem definidos
+- Projetos em equipe com múltiplos desenvolvedores no mesmo código
+- Aplicações onde a validação de dados é importante
+- Flows que precisam impor tipos de dados e restrições específicas
+
+## O ID de Estado Automático
+
+Tanto estados não estruturados quanto estruturados recebem automaticamente um identificador único (UUID) para ajudar a rastrear e gerenciar instâncias de estado.
+
+### Como Funciona
+
+- Para estado não estruturado, o ID é acessível via `self.state["id"]`
+- Para estado estruturado, o ID é acessível via `self.state.id`
+- Este ID é gerado automaticamente ao criar o flow
+- O ID permanece igual durante todo o ciclo de vida do flow
+- O ID pode ser usado para rastreamento, logs e recuperação de estados persistidos
+
+Este UUID é útil especialmente ao implementar persistência ou monitorar múltiplas execuções de flows.
+
+## Atualizações Dinâmicas de Estado
+
+Independente de você usar estado estruturado ou não estruturado, é possível atualizar o estado dinamicamente ao longo da execução do flow.
+
+### Passando Dados Entre Etapas
+
+Métodos do flow podem retornar valores que serão passados como argumento para métodos listeners:
+
+```python
+# código não traduzido
+```
+
+Esse padrão permite combinar passagem de dados direta com atualizações de estado para obter máxima flexibilidade.
+
+## Persistindo o Estado do Flow
+
+Uma das funcionalidades mais poderosas da CrewAI é a habilidade de persistir o estado do flow entre execuções. Isso habilita workflows que podem ser pausados, retomados e até recuperados após falhas.
+
+### O Decorador @persist()
+
+O decorador `@persist()` automatiza a persistência de estado, salvando o estado do flow em pontos chave da execução.
+
+#### Persistência em Nível de Classe
+
+Ao aplicar em nível de classe, `@persist()` salva o estado após cada execução de método:
+
+```python
+# código não traduzido
+```
+
+#### Persistência em Nível de Método
+
+Para mais controle, você pode aplicar `@persist()` em métodos específicos:
+
+```python
+# código não traduzido
+```
+
+## Padrões Avançados de Estado
+
+### Lógica Condicional Baseada no Estado
+
+Você pode usar o estado para implementar lógicas condicionais complexas em seus flows:
+
+```python
+# código não traduzido
+```
+
+### Manipulações Complexas de Estado
+
+Para transformar estados complexos, você pode criar métodos dedicados:
+
+```python
+# código não traduzido
+```
+
+Esse padrão de criar métodos auxiliares mantém seus métodos de flow limpos, enquanto permite manipulações complexas de estado.
+
+## Gerenciamento de Estado com Crews
+
+Um dos padrões mais poderosos na CrewAI é combinar o gerenciamento de estado do flow com a execução de crews.
+
+### Passando Estado para Crews
+
+Você pode usar o estado do flow para parametrizar crews:
+
+```python
+# código não traduzido
+```
+
+### Manipulando Saídas de Crews no Estado
+
+Quando um crew finaliza, é possível processar sua saída e armazená-la no estado do flow:
+
+```python
+# código não traduzido
+```
+
+## Boas Práticas para Gerenciamento de Estado
+
+### 1. Mantenha o Estado Focado
+
+Projete seu estado para conter somente o necessário:
+
+```python
+# Exemplo não traduzido
+```
+
+### 2. Use Estado Estruturado em Flows Complexos
+
+À medida que seus flows evoluem em complexidade, o estado estruturado se torna cada vez mais valioso:
+
+```python
+# Exemplo não traduzido
+```
+
+### 3. Documente Transições de Estado
+
+Para flows complexos, documente como o estado muda ao longo da execução:
+
+```python
+# Exemplo não traduzido
+```
+
+### 4. Trate Erros de Estado de Forma Elegante
+
+Implemente tratamento de erros ao acessar o estado:
+
+```python
+# Exemplo não traduzido
+```
+
+### 5. Use o Estado Para Acompanhar o Progresso
+
+Aproveite o estado para monitorar o progresso em flows de longa duração:
+
+```python
+# Exemplo não traduzido
+```
+
+### 6. Prefira Operações Imutáveis Quando Possível
+
+Especialmente com estado estruturado, prefira operações imutáveis para maior clareza:
+
+```python
+# Exemplo não traduzido
+```
+
+## Depurando o Estado do Flow
+
+### Logando Alterações no Estado
+
+Ao desenvolver, adicione logs para acompanhar mudanças no estado:
+
+```python
+# Exemplo não traduzido
+```
+
+### Visualizando o Estado
+
+Você pode adicionar métodos para visualizar seu estado durante o debug:
+
+```python
+# Exemplo não traduzido
+```
+
+## Conclusão
+
+Dominar o gerenciamento de estado em CrewAI Flows te dá poder para construir aplicações de IA sofisticadas e robustas, que mantêm contexto, tomam decisões complexas e entregam resultados consistentes.
+
+Seja escolhendo estado não estruturado ou estruturado, implementar boas práticas de gerenciamento de estado irá ajudar a criar flows manteníveis, extensíveis e eficazes na resolução de problemas do mundo real.
+
+À medida que desenvolver flows mais complexos, lembre-se de que um bom gerenciamento de estado está relacionado ao equilíbrio entre flexibilidade e estrutura, tornando seu código tanto poderoso quanto fácil de entender.
+
+<Check>
+Agora você domina os conceitos e práticas de gerenciamento de estado em CrewAI Flows! Com este conhecimento, você pode criar workflows de IA robustos que mantêm contexto, compartilham dados entre as etapas e constroem lógicas avançadas de aplicação.
+</Check>
+
+## Próximos Passos
+
+- Experimente usar estado estruturado e não estruturado em seus flows
+- Teste a implementação de persistência de estado para workflows de longa duração
+- Explore [como construir seu primeiro crew](/pt-BR/guides/crews/first-crew) para ver como crews e flows podem funcionar juntos
+- Confira a [documentação de referência de Flow](/pt-BR/concepts/flows) para funcionalidades mais avançadas