mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-05-01 15:22:37 +00:00
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
This commit is contained in:
Daniel Barreto
316
docs/pt-BR/guides/advanced/customizing-prompts.mdx
Normal file
316
docs/pt-BR/guides/advanced/customizing-prompts.mdx
Normal file
@@ -0,0 +1,316 @@
|
||||
---
|
||||
title: Personalizando Prompts
|
||||
description: Aprofunde-se na personalização de prompts de baixo nível no CrewAI, habilitando casos de uso super customizados e complexos para diferentes modelos e idiomas.
|
||||
icon: message-pen
|
||||
---
|
||||
|
||||
## Por Que Personalizar Prompts?
|
||||
|
||||
Embora os prompts padrão do CrewAI funcionem bem para muitos cenários, a personalização de baixo nível permite comportamentos de agentes significativamente mais flexíveis e poderosos. Veja por que você pode querer aproveitar esse controle mais profundo:
|
||||
|
||||
1. **Otimizar para LLMs específicas** – Diferentes modelos (como GPT-4, Claude ou Llama) funcionam melhor com formatos de prompt adaptados às suas arquiteturas exclusivas.
|
||||
2. **Alterar o idioma** – Construa agentes que operam exclusivamente em idiomas além do inglês, lidando com nuances com precisão.
|
||||
3. **Especializar para domínios complexos** – Adapte prompts para setores altamente especializados como saúde, finanças ou jurídico.
|
||||
4. **Ajustar tom e estilo** – Torne os agentes mais formais, casuais, criativos ou analíticos.
|
||||
5. **Suportar casos de uso super customizados** – Utilize estruturas e formatações avançadas de prompt para atender requisitos detalhados e específicos do projeto.
|
||||
|
||||
Este guia explora como acessar os prompts do CrewAI em um nível mais baixo, oferecendo controle granular sobre como os agentes pensam e interagem.
|
||||
|
||||
## Entendendo o Sistema de Prompt do CrewAI
|
||||
|
||||
Nos bastidores, o CrewAI adota um sistema de prompt modular que pode ser amplamente customizado:
|
||||
|
||||
- **Templates de agente** – Determinam o modo como cada agente aborda o papel que lhe foi atribuído.
|
||||
- **Prompt slices** – Controlam comportamentos especializados como tarefas, o uso de ferramentas e a estrutura de saída.
|
||||
- **Tratamento de erros** – Definem como os agentes respondem a falhas, exceções ou timeouts.
|
||||
- **Prompts específicos de ferramentas** – Definem instruções detalhadas para como as ferramentas são invocadas ou utilizadas.
|
||||
|
||||
Confira os [templates de prompt originais no repositório do CrewAI](https://github.com/crewAIInc/crewAI/blob/main/src/crewai/translations/en.json) para ver como esses elementos são organizados. A partir daí, você pode sobrescrever ou adaptar conforme necessário para desbloquear comportamentos avançados.
|
||||
|
||||
## Entendendo as Instruções de Sistema Padrão
|
||||
|
||||
<Warning>
|
||||
**Questão de Transparência em Produção**: O CrewAI injeta automaticamente instruções padrão nos seus prompts que talvez você não conheça. Esta seção explica o que acontece nos bastidores e como obter controle total.
|
||||
</Warning>
|
||||
|
||||
Ao definir um agente com `role`, `goal` e `backstory`, o CrewAI automaticamente adiciona instruções de sistema adicionais que controlam a formatação e o comportamento. Entender essas injeções padrão é essencial para sistemas em produção onde você precisa de total transparência nos prompts.
|
||||
|
||||
### O Que CrewAI Injeta Automaticamente
|
||||
|
||||
Baseado na configuração do seu agente, o CrewAI adiciona diferentes instruções padrão:
|
||||
|
||||
#### Para Agentes Sem Ferramentas
|
||||
```text
|
||||
"I MUST use these formats, my job depends on it!"
|
||||
```
|
||||
|
||||
#### Para Agentes Com Ferramentas
|
||||
```text
|
||||
"IMPORTANT: Use the following format in your response:
|
||||
|
||||
Thought: you should always think about what to do
|
||||
Action: the action to take, only one name of [tool_names]
|
||||
Action Input: the input to the action, just a simple JSON object...
|
||||
```
|
||||
|
||||
#### Para Saídas Estruturadas (JSON/Pydantic)
|
||||
```text
|
||||
"Ensure your final answer contains only the content in the following format: {output_format}
|
||||
Ensure the final output does not include any code block markers like ```json or ```python."
|
||||
```
|
||||
|
||||
### Visualizando o Prompt de Sistema Completo
|
||||
|
||||
Para ver exatamente qual prompt está sendo enviado para seu LLM, você pode inspecionar o prompt gerado:
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Task
|
||||
from crewai.utilities.prompts import Prompts
|
||||
|
||||
# Crie seu agente
|
||||
agent = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze data and provide insights",
|
||||
backstory="You are an expert data analyst with 10 years of experience.",
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Crie uma tarefa de exemplo
|
||||
task = Task(
|
||||
description="Analyze the sales data and identify trends",
|
||||
expected_output="A detailed analysis with key insights and trends",
|
||||
agent=agent
|
||||
)
|
||||
|
||||
# Crie o gerador de prompt
|
||||
prompt_generator = Prompts(
|
||||
agent=agent,
|
||||
has_tools=len(agent.tools) > 0,
|
||||
use_system_prompt=agent.use_system_prompt
|
||||
)
|
||||
|
||||
# Gere e inspecione o prompt atual
|
||||
generated_prompt = prompt_generator.task_execution()
|
||||
|
||||
# Imprima o prompt completo de sistema que será enviado ao LLM
|
||||
if "system" in generated_prompt:
|
||||
print("=== SYSTEM PROMPT ===")
|
||||
print(generated_prompt["system"])
|
||||
print("\n=== USER PROMPT ===")
|
||||
print(generated_prompt["user"])
|
||||
else:
|
||||
print("=== COMPLETE PROMPT ===")
|
||||
print(generated_prompt["prompt"])
|
||||
|
||||
# Você também pode ver como a descrição da tarefa é formatada
|
||||
print("\n=== TASK CONTEXT ===")
|
||||
print(f"Task Description: {task.description}")
|
||||
print(f"Expected Output: {task.expected_output}")
|
||||
```
|
||||
|
||||
### Sobrescrevendo Instruções Padrão
|
||||
|
||||
Você tem várias opções para obter controle total sobre os prompts:
|
||||
|
||||
#### Opção 1: Templates Personalizados (Recomendado)
|
||||
```python
|
||||
from crewai import Agent
|
||||
|
||||
# Defina seu próprio template de sistema sem instruções padrão
|
||||
custom_system_template = """You are {role}. {backstory}
|
||||
Your goal is: {goal}
|
||||
|
||||
Respond naturally and conversationally. Focus on providing helpful, accurate information."""
|
||||
|
||||
custom_prompt_template = """Task: {input}
|
||||
|
||||
Please complete this task thoughtfully."""
|
||||
|
||||
agent = Agent(
|
||||
role="Research Assistant",
|
||||
goal="Help users find accurate information",
|
||||
backstory="You are a helpful research assistant.",
|
||||
system_template=custom_system_template,
|
||||
prompt_template=custom_prompt_template,
|
||||
use_system_prompt=True # Use mensagens separadas system/user
|
||||
)
|
||||
```
|
||||
|
||||
#### Opção 2: Arquivo de Prompt Personalizado
|
||||
Crie um arquivo `custom_prompts.json` para sobrescrever slices específicas de prompt:
|
||||
|
||||
```json
|
||||
{
|
||||
"slices": {
|
||||
"no_tools": "\nProvide your best answer in a natural, conversational way.",
|
||||
"tools": "\nYou have access to these tools: {tools}\n\nUse them when helpful, but respond naturally.",
|
||||
"formatted_task_instructions": "Format your response as: {output_format}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Em seguida, utilize no seu crew:
|
||||
|
||||
```python
|
||||
crew = Crew(
|
||||
agents=[agent],
|
||||
tasks=[task],
|
||||
prompt_file="custom_prompts.json",
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
#### Opção 3: Desativar Prompts de Sistema para Modelos o1
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Analyst",
|
||||
goal="Analyze data",
|
||||
backstory="Expert analyst",
|
||||
use_system_prompt=False # Desativa separação de mensagens system prompt
|
||||
)
|
||||
```
|
||||
|
||||
### Depuração com Ferramentas de Observabilidade
|
||||
|
||||
Para garantir transparência em produção, integre com plataformas de observabilidade para monitorar todos os prompts e interações com LLM. Isso permite que você veja exatamente quais prompts (incluindo instruções padrão) estão sendo enviados para os seus LLMs.
|
||||
|
||||
Veja nossa [documentação sobre Observabilidade](/pt-BR/observability/overview) para guias detalhados de integração com diversas plataformas como Langfuse, MLflow, Weights & Biases e soluções de logging customizadas.
|
||||
|
||||
### Boas Práticas para Produção
|
||||
|
||||
1. **Sempre inspecione prompts gerados** antes de implantar em produção
|
||||
2. **Use templates customizados** quando precisar de controle total sobre o conteúdo do prompt
|
||||
3. **Integre ferramentas de observabilidade** para monitoramento contínuo de prompts (veja [docs de Observabilidade](/pt-BR/observability/overview))
|
||||
4. **Teste com diferentes LLMs** já que instruções padrão podem se comportar de maneira diferente em cada modelo
|
||||
5. **Documente suas customizações de prompt** para transparência da equipe
|
||||
|
||||
<Tip>
|
||||
As instruções padrão existem para garantir comportamento consistente nos agentes, mas podem interferir com requisitos de domínio específicos. Use as opções de customização acima para manter controle total sobre o comportamento do seu agente em sistemas de produção.
|
||||
</Tip>
|
||||
|
||||
## Melhores Práticas para Gerenciar Arquivos de Prompt
|
||||
|
||||
Ao realizar personalização de prompts em baixo nível, siga estas diretrizes para manter tudo organizado e fácil de manter:
|
||||
|
||||
1. **Mantenha arquivos separados** – Armazene seus prompts personalizados em arquivos JSON dedicados fora do código principal.
|
||||
2. **Controle de versão** – Acompanhe as alterações no seu repositório, garantindo documentação clara das mudanças nos prompts ao longo do tempo.
|
||||
3. **Organize por modelo ou idioma** – Utilize nomes como `prompts_llama.json` ou `prompts_es.json` para identificar rapidamente configurações especializadas.
|
||||
4. **Documente as alterações** – Adicione comentários ou mantenha um README detalhando o propósito e o escopo das customizações.
|
||||
5. **Minimize alterações** – Sobrescreva apenas os slices específicos que realmente precisam de ajuste, mantendo a funcionalidade padrão para o restante.
|
||||
|
||||
## O Jeito Mais Simples de Personalizar Prompts
|
||||
|
||||
Uma abordagem direta é criar um arquivo JSON para os prompts que deseja sobrescrever e então indicar este arquivo no seu Crew:
|
||||
|
||||
1. Crie um arquivo JSON com os slices de prompt atualizados.
|
||||
2. Referencie este arquivo no parâmetro `prompt_file` do seu Crew.
|
||||
|
||||
O CrewAI então mescla suas customizações com os padrões, assim você não precisa redefinir todos os prompts. Veja como:
|
||||
|
||||
### Exemplo: Customização Básica de Prompt
|
||||
|
||||
Crie um arquivo `custom_prompts.json` com os prompts que deseja modificar. Certifique-se de listar todos os prompts de nível superior que ele deve conter, não apenas suas alterações:
|
||||
|
||||
```json
|
||||
{
|
||||
"slices": {
|
||||
"format": "When responding, follow this structure:\n\nTHOUGHTS: Your step-by-step thinking\nACTION: Any tool you're using\nRESULT: Your final answer or conclusion"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Integre assim:
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Task, Process
|
||||
|
||||
# Crie agentes e tarefas normalmente
|
||||
researcher = Agent(
|
||||
role="Research Specialist",
|
||||
goal="Find information on quantum computing",
|
||||
backstory="You are a quantum physics expert",
|
||||
verbose=True
|
||||
)
|
||||
|
||||
research_task = Task(
|
||||
description="Research quantum computing applications",
|
||||
expected_output="A summary of practical applications",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
# Crie um crew com seu arquivo de prompt personalizado
|
||||
crew = Crew(
|
||||
agents=[researcher],
|
||||
tasks=[research_task],
|
||||
prompt_file="path/to/custom_prompts.json",
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Execute o crew
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
Com essas poucas edições, você conquista controle de baixo nível sobre como seus agentes se comunicam e solucionam tarefas.
|
||||
|
||||
## Otimizando para Modelos Específicos
|
||||
|
||||
Modelos diferentes respondem melhor a estruturas de prompt diferentes. Ajustes mais profundos podem aumentar significativamente o desempenho ao alinhar seus prompts às nuances de cada modelo.
|
||||
|
||||
### Exemplo: Template de Prompt para Llama 3.3
|
||||
|
||||
Por exemplo, ao lidar com o Llama 3.3 da Meta, a personalização de baixo nível pode refletir a estrutura recomendada descrita em:
|
||||
https://www.llama.com/docs/model-cards-and-prompt-formats/llama3_1/#prompt-template
|
||||
|
||||
Veja um exemplo destacando como você pode ajustar um Agent para usar o Llama 3.3 em código:
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Task, Process
|
||||
from crewai_tools import DirectoryReadTool, FileReadTool
|
||||
|
||||
# Defina templates para mensagens de system, user (prompt) e assistant (resposta)
|
||||
system_template = """<|begin_of_text|><|start_header_id|>system<|end_header_id|>{{ .System }}<|eot_id|>"""
|
||||
prompt_template = """<|start_header_id|>user<|end_header_id|>{{ .Prompt }}<|eot_id|>"""
|
||||
response_template = """<|start_header_id|>assistant<|end_header_id|>{{ .Response }}<|eot_id|>"""
|
||||
|
||||
# Crie um Agent usando layouts específicos do Llama
|
||||
principal_engineer = Agent(
|
||||
role="Principal Engineer",
|
||||
goal="Oversee AI architecture and make high-level decisions",
|
||||
backstory="You are the lead engineer responsible for critical AI systems",
|
||||
verbose=True,
|
||||
llm="groq/llama-3.3-70b-versatile", # Usando o modelo Llama 3
|
||||
system_template=system_template,
|
||||
prompt_template=prompt_template,
|
||||
response_template=response_template,
|
||||
tools=[DirectoryReadTool(), FileReadTool()]
|
||||
)
|
||||
|
||||
# Defina uma tarefa de exemplo
|
||||
engineering_task = Task(
|
||||
description="Review AI implementation files for potential improvements",
|
||||
expected_output="A summary of key findings and recommendations",
|
||||
agent=principal_engineer
|
||||
)
|
||||
|
||||
# Crie um Crew para a tarefa
|
||||
llama_crew = Crew(
|
||||
agents=[principal_engineer],
|
||||
tasks=[engineering_task],
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Execute o crew
|
||||
result = llama_crew.kickoff()
|
||||
print(result.raw)
|
||||
```
|
||||
|
||||
Com essa configuração, você exerce controle abrangente e de baixo nível sobre seus fluxos de trabalho baseados em Llama sem precisar de um arquivo JSON separado.
|
||||
|
||||
## Conclusão
|
||||
|
||||
A personalização de prompts em baixo nível no CrewAI abre portas para casos de uso super customizados e complexos. Mantendo arquivos de prompt organizados (ou templates inline diretos), é possível acomodar diferentes modelos, idiomas e domínios especializados. Esse nível de flexibilidade garante que você possa criar exatamente o comportamento de IA que precisa, sabendo que o CrewAI ainda fornece padrões confiáveis quando você não sobrescreve.
|
||||
|
||||
<Check>
|
||||
Agora você tem a base para customizações avançadas de prompt no CrewAI. Seja adaptando para estruturas específicas de modelo ou restrições de domínio, esta abordagem de baixo nível permite moldar as interações dos agentes de forma altamente especializada.
|
||||
</Check>
|
||||
133
docs/pt-BR/guides/advanced/fingerprinting.mdx
Normal file
133
docs/pt-BR/guides/advanced/fingerprinting.mdx
Normal file
@@ -0,0 +1,133 @@
|
||||
---
|
||||
title: Impressão digital
|
||||
description: Saiba como usar o sistema de impressão digital da CrewAI para identificar e rastrear componentes de forma única durante todo o seu ciclo de vida.
|
||||
icon: fingerprint
|
||||
---
|
||||
|
||||
## Visão geral
|
||||
|
||||
As impressões digitais na CrewAI fornecem uma maneira de identificar e rastrear componentes de forma única durante todo o seu ciclo de vida. Cada `Agent`, `Crew` e `Task` recebe automaticamente uma impressão digital única quando criado, que não pode ser sobrescrita manualmente.
|
||||
|
||||
Essas impressões digitais podem ser usadas para:
|
||||
- Auditoria e rastreamento do uso de componentes
|
||||
- Garantir a integridade da identidade dos componentes
|
||||
- Anexar metadados aos componentes
|
||||
- Criar uma cadeia rastreável de operações
|
||||
|
||||
## Como funciona a impressão digital
|
||||
|
||||
Uma impressão digital é uma instância da classe `Fingerprint` do módulo `crewai.security`. Cada impressão digital contém:
|
||||
|
||||
- Uma string UUID: Um identificador único para o componente, gerado automaticamente e que não pode ser definido manualmente
|
||||
- Um timestamp de criação: Quando a impressão digital foi gerada, definido automaticamente e que não pode ser modificado manualmente
|
||||
- Metadados: Um dicionário de informações adicionais que pode ser customizado
|
||||
|
||||
As impressões digitais são geradas e atribuídas automaticamente quando um componente é criado. Cada componente expõe sua impressão digital por meio de uma propriedade de somente leitura.
|
||||
|
||||
## Uso básico
|
||||
|
||||
### Acessando impressões digitais
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Task
|
||||
|
||||
# Criar componentes - impressões digitais são geradas automaticamente
|
||||
agent = Agent(
|
||||
role="Data Scientist",
|
||||
goal="Analyze data",
|
||||
backstory="Expert in data analysis"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[agent],
|
||||
tasks=[]
|
||||
)
|
||||
|
||||
task = Task(
|
||||
description="Analyze customer data",
|
||||
expected_output="Insights from data analysis",
|
||||
agent=agent
|
||||
)
|
||||
|
||||
# Acessar as impressões digitais
|
||||
agent_fingerprint = agent.fingerprint
|
||||
crew_fingerprint = crew.fingerprint
|
||||
task_fingerprint = task.fingerprint
|
||||
|
||||
# Imprimir as strings UUID
|
||||
print(f"Agent fingerprint: {agent_fingerprint.uuid_str}")
|
||||
print(f"Crew fingerprint: {crew_fingerprint.uuid_str}")
|
||||
print(f"Task fingerprint: {task_fingerprint.uuid_str}")
|
||||
```
|
||||
|
||||
### Trabalhando com metadados das impressões digitais
|
||||
|
||||
Você pode adicionar metadados às impressões digitais para fornecer contexto adicional:
|
||||
|
||||
```python
|
||||
# Adicionar metadados à impressão digital do agente
|
||||
agent.security_config.fingerprint.metadata = {
|
||||
"version": "1.0",
|
||||
"department": "Data Science",
|
||||
"project": "Customer Analysis"
|
||||
}
|
||||
|
||||
# Acessar os metadados
|
||||
print(f"Agent metadata: {agent.fingerprint.metadata}")
|
||||
```
|
||||
|
||||
## Persistência das impressões digitais
|
||||
|
||||
As impressões digitais foram projetadas para persistir e permanecer inalteradas durante todo o ciclo de vida de um componente. Se você modificar um componente, a impressão digital permanece a mesma:
|
||||
|
||||
```python
|
||||
original_fingerprint = agent.fingerprint.uuid_str
|
||||
|
||||
# Modificar o agente
|
||||
agent.goal = "New goal for analysis"
|
||||
|
||||
# A impressão digital permanece inalterada
|
||||
assert agent.fingerprint.uuid_str == original_fingerprint
|
||||
```
|
||||
|
||||
## Impressões digitais determinísticas
|
||||
|
||||
Apesar de não ser possível definir diretamente o UUID e o timestamp de criação, é possível criar impressões digitais determinísticas usando o método `generate` com uma seed:
|
||||
|
||||
```python
|
||||
from crewai.security import Fingerprint
|
||||
|
||||
# Criar uma impressão digital determinística usando uma string seed
|
||||
deterministic_fingerprint = Fingerprint.generate(seed="my-agent-id")
|
||||
|
||||
# A mesma seed sempre gera a mesma impressão digital
|
||||
same_fingerprint = Fingerprint.generate(seed="my-agent-id")
|
||||
assert deterministic_fingerprint.uuid_str == same_fingerprint.uuid_str
|
||||
|
||||
# Também é possível definir metadados
|
||||
custom_fingerprint = Fingerprint.generate(
|
||||
seed="my-agent-id",
|
||||
metadata={"version": "1.0"}
|
||||
)
|
||||
```
|
||||
|
||||
## Uso avançado
|
||||
|
||||
### Estrutura da impressão digital
|
||||
|
||||
Cada impressão digital possui a seguinte estrutura:
|
||||
|
||||
```python
|
||||
from crewai.security import Fingerprint
|
||||
|
||||
fingerprint = agent.fingerprint
|
||||
|
||||
# String UUID - identificador único (gerado automaticamente)
|
||||
uuid_str = fingerprint.uuid_str # e.g., "123e4567-e89b-12d3-a456-426614174000"
|
||||
|
||||
# Timestamp de criação (gerado automaticamente)
|
||||
created_at = fingerprint.created_at # Um objeto datetime
|
||||
|
||||
# Metadados - informações adicionais (podem ser customizadas)
|
||||
metadata = fingerprint.metadata # Um dicionário, padrão {}
|
||||
```
|
||||
452
docs/pt-BR/guides/agents/crafting-effective-agents.mdx
Normal file
452
docs/pt-BR/guides/agents/crafting-effective-agents.mdx
Normal file
@@ -0,0 +1,452 @@
|
||||
---
|
||||
title: Criando Agentes Eficazes
|
||||
description: Aprenda as melhores práticas para projetar agentes de IA poderosos e especializados que colaboram de forma eficaz para resolver problemas complexos.
|
||||
icon: robot
|
||||
---
|
||||
|
||||
## A Arte e a Ciência do Design de Agentes
|
||||
|
||||
No núcleo do CrewAI está o agente – uma entidade de IA especializada projetada para desempenhar funções específicas dentro de um framework colaborativo. Embora criar agentes básicos seja simples, criar agentes verdadeiramente eficazes que geram resultados excepcionais requer a compreensão de princípios fundamentais de design e boas práticas.
|
||||
|
||||
Este guia vai ajudá-lo a dominar a arte de projetar agentes, permitindo criar personas de IA especializadas que colaboram de forma eficaz, pensam criticamente e produzem resultados de alta qualidade adaptados às suas necessidades específicas.
|
||||
|
||||
### Por Que o Design de Agentes é Importante
|
||||
|
||||
A forma como você define seus agentes impacta significativamente:
|
||||
|
||||
1. **Qualidade do resultado**: Agentes bem projetados produzem resultados mais relevantes e de alta qualidade
|
||||
2. **Eficiência da colaboração**: Agentes com habilidades complementares trabalham juntos de maneira mais eficiente
|
||||
3. **Desempenho nas tarefas**: Agentes com papéis e objetivos claros executam tarefas de forma mais eficaz
|
||||
4. **Escalabilidade do sistema**: Agentes bem projetados podem ser reutilizados em múltiplos crews e contextos
|
||||
|
||||
Vamos explorar as melhores práticas para criar agentes que se destacam nessas dimensões.
|
||||
|
||||
## A Regra 80/20: Foque Mais nas Tarefas do que nos Agentes
|
||||
|
||||
Ao construir sistemas de IA eficazes, lembre-se deste princípio crucial: **80% do seu esforço deve ser dedicado ao design das tarefas, e apenas 20% à definição dos agentes**.
|
||||
|
||||
Por quê? Porque mesmo o agente mais perfeitamente definido irá falhar com tarefas mal elaboradas, mas tarefas bem projetadas podem elevar até mesmo agentes simples. Isso significa:
|
||||
|
||||
- Dedique a maior parte do seu tempo escrevendo instruções claras para as tarefas
|
||||
- Defina entradas detalhadas e saídas esperadas
|
||||
- Adicione exemplos e contexto para orientar a execução
|
||||
- Reserve o tempo restante para o papel, objetivo e histórico do agente
|
||||
|
||||
Isso não quer dizer que o design do agente não seja importante – ele é, sim. Mas o design das tarefas é onde ocorrem a maioria das falhas de execução, então priorize de acordo.
|
||||
|
||||
## Princípios Fundamentais do Design de Agentes Eficazes
|
||||
|
||||
### 1. O Framework Papel–Objetivo–Histórico
|
||||
|
||||
Os agentes mais poderosos no CrewAI têm uma base sólida em três elementos-chave:
|
||||
|
||||
#### Papel: A Função Especializada do Agente
|
||||
|
||||
O papel define o que o agente faz e sua área de especialização. Ao criar papéis:
|
||||
|
||||
- **Seja específico e especializado**: Em vez de “Escritor”, use “Especialista em Documentação Técnica” ou “Contador de Histórias Criativo”
|
||||
- **Alinhe com profissões do mundo real**: Baseie os papéis em arquétipos profissionais reconhecíveis
|
||||
- **Inclua expertise no domínio**: Especifique o campo de conhecimento do agente (ex: “Analista Financeiro especializado em tendências de mercado”)
|
||||
|
||||
**Exemplos de papéis eficazes:**
|
||||
```yaml
|
||||
role: "Pesquisador Sênior de UX especializado em análise de entrevistas com usuários"
|
||||
role: "Arquiteto de Software Full-Stack com expertise em sistemas distribuídos"
|
||||
role: "Diretor de Comunicação Corporativa especializado em gestão de crises"
|
||||
```
|
||||
|
||||
#### Objetivo: A Finalidade e Motivação do Agente
|
||||
|
||||
O objetivo direciona os esforços do agente e orienta seu processo de tomada de decisão. Objetivos eficazes devem:
|
||||
|
||||
- **Ser claros e focados em resultado**: Defina o que o agente precisa alcançar
|
||||
- **Enfatizar padrões de qualidade**: Inclua expectativas sobre a qualidade do trabalho
|
||||
- **Incorporar critérios de sucesso**: Ajude o agente a entender o que é considerado “bom”
|
||||
|
||||
**Exemplos de objetivos eficazes:**
|
||||
```yaml
|
||||
goal: "Descobrir insights acionáveis analisando dados de entrevistas, identificando padrões recorrentes, necessidades não atendidas e oportunidades de melhoria"
|
||||
goal: "Projetar arquiteturas de sistemas robustas e escaláveis que equilibrem performance, manutenção e custo-benefício"
|
||||
goal: "Criar comunicações de crise claras e empáticas, abordando as preocupações das partes interessadas e protegendo a reputação organizacional"
|
||||
```
|
||||
|
||||
#### Histórico: Experiência e Perspectiva do Agente
|
||||
|
||||
O histórico aprofunda o agente, influenciando como ele aborda problemas e interage com os demais. Bons históricos:
|
||||
|
||||
- **Estabelecem expertise e experiência**: Explique como o agente adquiriu suas habilidades
|
||||
- **Definem estilo de trabalho e valores**: Descreva como o agente encara seu trabalho
|
||||
- **Criam uma persona coesa**: Garanta que todos os elementos do histórico estejam alinhados ao papel e ao objetivo
|
||||
|
||||
**Exemplos de históricos eficazes:**
|
||||
```yaml
|
||||
backstory: "Você passou 15 anos conduzindo e analisando pesquisas com usuários em grandes empresas de tecnologia. Tem talento para ler nas entrelinhas e identificar padrões que outros não enxergam. Acredita que uma boa experiência do usuário é invisível e que os melhores insights vêm tanto do que os usuários não dizem quanto do que dizem."
|
||||
|
||||
backstory: "Com mais de 20 anos de experiência construindo sistemas distribuídos em larga escala, você desenvolveu uma abordagem pragmática para arquitetura de software. Viu sistemas bem sucedidos e fracassados e aprendeu lições valiosas com ambos. Equilibra as melhores práticas teóricas com restrições práticas e sempre considera os aspectos de manutenção e operação em seus projetos."
|
||||
|
||||
backstory: "Como um profissional de comunicação experiente que já orientou múltiplas organizações em crises de grande repercussão, você entende a importância da transparência, agilidade e empatia em respostas a crises. Tem uma abordagem metódica para criar mensagens que abordam preocupações mantendo a credibilidade da organização."
|
||||
```
|
||||
|
||||
### 2. Especialistas em vez de Generalistas
|
||||
|
||||
Agentes desempenham muito melhor quando recebem papéis especializados em vez de papéis genéricos. Um agente altamente focado gera resultados mais precisos e relevantes:
|
||||
|
||||
**Genérico (Menos Eficaz):**
|
||||
```yaml
|
||||
role: "Writer"
|
||||
```
|
||||
|
||||
**Especializado (Mais Eficaz):**
|
||||
```yaml
|
||||
role: "Redator Técnico de Blog especializado em explicar conceitos complexos de IA para públicos não técnicos"
|
||||
```
|
||||
|
||||
**Vantagens dos Especialistas:**
|
||||
- Compreensão mais clara do resultado esperado
|
||||
- Performance mais consistente
|
||||
- Melhor alinhamento com tarefas específicas
|
||||
- Maior capacidade de fazer julgamentos específicos do domínio
|
||||
|
||||
### 3. Equilibrando Especialização e Versatilidade
|
||||
|
||||
Agentes eficazes equilibram bem a especialização (fazer uma coisa muito bem) e a versatilidade (adaptar-se a diversas situações):
|
||||
|
||||
- **Especialize no papel, seja versátil na aplicação**: Crie agentes com habilidades especializadas aplicáveis em múltiplos contextos
|
||||
- **Evite definições excessivamente restritas**: Garanta que agentes possam lidar com variações dentro de sua área de expertise
|
||||
- **Considere o contexto colaborativo**: Projete agentes cujas especialidades complementem os demais do crew
|
||||
|
||||
### 4. Definição Nível Apropriado de Expertise
|
||||
|
||||
O nível de expertise atribuído ao agente determina como ele realiza as tarefas:
|
||||
|
||||
- **Agentes iniciantes**: Bons para tarefas simples, brainstorm, rascunhos iniciais
|
||||
- **Agentes intermediários**: Adequados para a maioria das tarefas padrão com execução confiável
|
||||
- **Agentes especialistas**: Ideais para tarefas complexas e especializadas que exigem profundidade e nuances
|
||||
- **Agentes de classe mundial**: Reservados para tarefas críticas onde a qualidade excepcional é essencial
|
||||
|
||||
Escolha o nível de expertise baseado na complexidade da tarefa e no padrão de qualidade exigido. Em crews colaborativos, tendem a funcionar melhor equipes com níveis variados de expertise, reservando maior especialização para as funções mais chave.
|
||||
|
||||
## Exemplos Práticos: Antes e Depois
|
||||
|
||||
Veja exemplos de definições de agentes antes e depois de aplicar essas boas práticas:
|
||||
|
||||
### Exemplo 1: Agente de Criação de Conteúdo
|
||||
|
||||
**Antes:**
|
||||
```yaml
|
||||
role: "Writer"
|
||||
goal: "Write good content"
|
||||
backstory: "You are a writer who creates content for websites."
|
||||
```
|
||||
|
||||
**Depois:**
|
||||
```yaml
|
||||
role: "Estrategista de Conteúdo B2B para Tecnologia"
|
||||
goal: "Criar conteúdos envolventes e tecnicamente precisos, explicando tópicos complexos em linguagem acessível, promovendo engajamento e apoiando os objetivos do negócio"
|
||||
backstory: "Você passou uma década criando conteúdos para empresas líderes em tecnologia, especializando-se na tradução de conceitos técnicos para públicos empresariais. É ótimo em pesquisa, entrevistas com especialistas e estruturação da informação para máxima clareza e impacto. Acredita que o melhor conteúdo B2B educa antes de vender, construindo confiança através da expertise genuína e não do hype de marketing."
|
||||
```
|
||||
|
||||
### Exemplo 2: Agente de Pesquisa
|
||||
|
||||
**Antes:**
|
||||
```yaml
|
||||
role: "Researcher"
|
||||
goal: "Find information"
|
||||
backstory: "You are good at finding information online."
|
||||
```
|
||||
|
||||
**Depois:**
|
||||
```yaml
|
||||
role: "Especialista em Pesquisa Acadêmica de Tecnologias Emergentes"
|
||||
goal: "Descobrir e sintetizar pesquisas de ponta, identificando tendências, metodologias e resultados principais, avaliando a qualidade e confiabilidade das fontes"
|
||||
backstory: "Com formação em ciência da computação e biblioteconomia, você dominou a arte da pesquisa digital. Já trabalhou com equipes de pesquisa em universidades de prestígio e sabe como navegar bancos de dados acadêmicos, avaliar a qualidade das pesquisas e sintetizar descobertas em diferentes áreas. Seu método é rigoroso: sempre cruza informações e rastreia a origem dos dados antes de chegar a conclusões."
|
||||
```
|
||||
|
||||
## Criando Tarefas Eficazes para seus Agentes
|
||||
|
||||
Embora o design dos agentes seja importante, o design das tarefas é crítico para uma boa execução. Aqui estão as melhores práticas para definir tarefas que irão impulsionar o sucesso dos seus agentes:
|
||||
|
||||
### A Anatomia de uma Tarefa Eficaz
|
||||
|
||||
Uma tarefa bem projetada tem dois componentes-chave com propósitos distintos:
|
||||
|
||||
#### Descrição da Tarefa: O Processo
|
||||
A descrição deve focar no que fazer e como fazer, incluindo:
|
||||
- Instruções detalhadas de execução
|
||||
- Contexto e informações de fundo
|
||||
- Escopo e restrições
|
||||
- Passos do processo a serem seguidos
|
||||
|
||||
#### Saída Esperada: O Entregável
|
||||
A saída esperada deve definir como o resultado final deve ser apresentado:
|
||||
- Especificações de formato (markdown, JSON, etc.)
|
||||
- Estrutura exigida
|
||||
- Critérios de qualidade
|
||||
- Exemplos de bons entregáveis (sempre que possível)
|
||||
|
||||
### Melhores Práticas para Design de Tarefas
|
||||
|
||||
#### 1. Propósito Único, Saída Única
|
||||
Tarefas funcionam melhor quando são focadas em um objetivo claro:
|
||||
|
||||
**Exemplo Ruim (Muito Abrangente):**
|
||||
```yaml
|
||||
task_description: "Research market trends, analyze the data, and create a visualization."
|
||||
```
|
||||
|
||||
**Exemplo Bom (Focado):**
|
||||
```yaml
|
||||
# Task 1
|
||||
research_task:
|
||||
description: "Research the top 5 market trends in the AI industry for 2024."
|
||||
expected_output: "A markdown list of the 5 trends with supporting evidence."
|
||||
|
||||
# Task 2
|
||||
analysis_task:
|
||||
description: "Analyze the identified trends to determine potential business impacts."
|
||||
expected_output: "A structured analysis with impact ratings (High/Medium/Low)."
|
||||
|
||||
# Task 3
|
||||
visualization_task:
|
||||
description: "Create a visual representation of the analyzed trends."
|
||||
expected_output: "A description of a chart showing trends and their impact ratings."
|
||||
```
|
||||
|
||||
#### 2. Seja Explícito Sobre Entradas e Saídas
|
||||
Sempre especifique claramente quais são as entradas da tarefa e como deve ser o resultado:
|
||||
|
||||
**Exemplo:**
|
||||
```yaml
|
||||
analysis_task:
|
||||
description: >
|
||||
Analyze the customer feedback data from the CSV file.
|
||||
Focus on identifying recurring themes related to product usability.
|
||||
Consider sentiment and frequency when determining importance.
|
||||
expected_output: >
|
||||
A markdown report with the following sections:
|
||||
1. Executive summary (3-5 bullet points)
|
||||
2. Top 3 usability issues with supporting data
|
||||
3. Recommendations for improvement
|
||||
```
|
||||
|
||||
#### 3. Inclua Propósito e Contexto
|
||||
Explique por que a tarefa importa e como ela se encaixa no fluxo de trabalho maior:
|
||||
|
||||
**Exemplo:**
|
||||
```yaml
|
||||
competitor_analysis_task:
|
||||
description: >
|
||||
Analyze our three main competitors' pricing strategies.
|
||||
This analysis will inform our upcoming pricing model revision.
|
||||
Focus on identifying patterns in how they price premium features
|
||||
and how they structure their tiered offerings.
|
||||
```
|
||||
|
||||
#### 4. Use Ferramentas de Saída Estruturada
|
||||
Para saídas legíveis por máquina, especifique claramente o formato:
|
||||
|
||||
**Exemplo:**
|
||||
```yaml
|
||||
data_extraction_task:
|
||||
description: "Extract key metrics from the quarterly report."
|
||||
expected_output: "JSON object with the following keys: revenue, growth_rate, customer_acquisition_cost, and retention_rate."
|
||||
```
|
||||
|
||||
## Erros Comuns a Evitar
|
||||
|
||||
Baseando-se em experiências de casos reais, estes são os erros mais comuns no design de agentes e tarefas:
|
||||
|
||||
### 1. Instruções de Tarefa Pouco Claras
|
||||
|
||||
**Problema:** Tarefas sem detalhes suficientes, dificultando a execução pelo agente.
|
||||
|
||||
**Exemplo de Design Ruim:**
|
||||
```yaml
|
||||
research_task:
|
||||
description: "Research AI trends."
|
||||
expected_output: "A report on AI trends."
|
||||
```
|
||||
|
||||
**Versão Melhorada:**
|
||||
```yaml
|
||||
research_task:
|
||||
description: >
|
||||
Research the top emerging AI trends for 2024 with a focus on:
|
||||
1. Enterprise adoption patterns
|
||||
2. Technical breakthroughs in the past 6 months
|
||||
3. Regulatory developments affecting implementation
|
||||
|
||||
For each trend, identify key companies, technologies, and potential business impacts.
|
||||
expected_output: >
|
||||
A comprehensive markdown report with:
|
||||
- Executive summary (5 bullet points)
|
||||
- 5-7 major trends with supporting evidence
|
||||
- For each trend: definition, examples, and business implications
|
||||
- References to authoritative sources
|
||||
```
|
||||
|
||||
### 2. "Tarefas-Deus" Que Tentam Fazer Demais
|
||||
|
||||
**Problema:** Tarefas que combinam múltiplas operações complexas em um único conjunto de instruções.
|
||||
|
||||
**Exemplo de Design Ruim:**
|
||||
```yaml
|
||||
comprehensive_task:
|
||||
description: "Research market trends, analyze competitor strategies, create a marketing plan, and design a launch timeline."
|
||||
```
|
||||
|
||||
**Versão Melhorada:**
|
||||
Divida em tarefas sequenciais e focadas:
|
||||
```yaml
|
||||
# Task 1: Research
|
||||
market_research_task:
|
||||
description: "Research current market trends in the SaaS project management space."
|
||||
expected_output: "A markdown summary of key market trends."
|
||||
|
||||
# Task 2: Competitive Analysis
|
||||
competitor_analysis_task:
|
||||
description: "Analyze strategies of the top 3 competitors based on the market research."
|
||||
expected_output: "A comparison table of competitor strategies."
|
||||
context: [market_research_task]
|
||||
|
||||
# Continue with additional focused tasks...
|
||||
```
|
||||
|
||||
### 3. Descrição e Saída Esperada Desalinhadas
|
||||
|
||||
**Problema:** O que a descrição pede não corresponde ao que a saída esperada especifica.
|
||||
|
||||
**Exemplo de Design Ruim:**
|
||||
```yaml
|
||||
analysis_task:
|
||||
description: "Analyze customer feedback to find areas of improvement."
|
||||
expected_output: "A marketing plan for the next quarter."
|
||||
```
|
||||
|
||||
**Versão Melhorada:**
|
||||
```yaml
|
||||
analysis_task:
|
||||
description: "Analyze customer feedback to identify the top 3 areas for product improvement."
|
||||
expected_output: "A report listing the 3 priority improvement areas with supporting customer quotes and data points."
|
||||
```
|
||||
|
||||
### 4. Não Entender o Processo Você Mesmo
|
||||
|
||||
**Problema:** Pedir para o agente executar tarefas que você mesmo não entende completamente.
|
||||
|
||||
**Solução:**
|
||||
1. Tente realizar a tarefa manualmente primeiro
|
||||
2. Documente o processo, pontos de decisão e fontes de informação
|
||||
3. Use esta documentação como base para a descrição da tarefa
|
||||
|
||||
### 5. Uso Prematuro de Estruturas Hierárquicas
|
||||
|
||||
**Problema:** Criar hierarquias de agentes desnecessariamente complexas quando processos sequenciais seriam suficientes.
|
||||
|
||||
**Solução:** Comece com processos sequenciais e só adote modelos hierárquicos quando a complexidade do fluxo de trabalho realmente justificar.
|
||||
|
||||
### 6. Definições Genéricas ou Pouco Claras de Agentes
|
||||
|
||||
**Problema:** Definições genéricas de agentes levam a resultados genéricos.
|
||||
|
||||
**Exemplo de Design Ruim:**
|
||||
```yaml
|
||||
agent:
|
||||
role: "Business Analyst"
|
||||
goal: "Analyze business data"
|
||||
backstory: "You are good at business analysis."
|
||||
```
|
||||
|
||||
**Versão Melhorada:**
|
||||
```yaml
|
||||
agent:
|
||||
role: "Especialista em Métricas SaaS focado em startups em fase de crescimento"
|
||||
goal: "Identificar insights acionáveis em dados de negócios que possam impactar diretamente a retenção de clientes e o crescimento de receita"
|
||||
backstory: "Com mais de 10 anos analisando modelos de negócios SaaS, você desenvolveu um olhar apurado para as métricas que realmente impulsionam crescimento sustentável. Já ajudou diversas empresas a identificar pontos de alavancagem que mudaram o rumo dos negócios. Acredita em conectar dados a recomendações específicas e acionáveis, e não apenas a observações genéricas."
|
||||
```
|
||||
|
||||
## Estratégias Avançadas de Design de Agentes
|
||||
|
||||
### Projetando para Colaboração
|
||||
|
||||
Ao criar agentes que trabalharão em conjunto em um crew, pense em:
|
||||
|
||||
- **Habilidades complementares**: Projete agentes com competências distintas, porém complementares
|
||||
- **Pontos de transferência**: Defina interfaces claras para a passagem de trabalho entre agentes
|
||||
- **Tensão construtiva**: Às vezes, agentes com perspectivas um pouco diferentes promovem melhores resultados por meio de diálogos construtivos
|
||||
|
||||
Por exemplo, um crew de criação de conteúdo pode incluir:
|
||||
|
||||
```yaml
|
||||
# Research Agent
|
||||
role: "Research Specialist for technical topics"
|
||||
goal: "Gather comprehensive, accurate information from authoritative sources"
|
||||
backstory: "You are a meticulous researcher with a background in library science..."
|
||||
|
||||
# Writer Agent
|
||||
role: "Technical Content Writer"
|
||||
goal: "Transform research into engaging, clear content that educates and informs"
|
||||
backstory: "You are an experienced writer who excels at explaining complex concepts..."
|
||||
|
||||
# Editor Agent
|
||||
role: "Content Quality Editor"
|
||||
goal: "Ensure content is accurate, well-structured, and polished while maintaining consistency"
|
||||
backstory: "With years of experience in publishing, you have a keen eye for detail..."
|
||||
```
|
||||
|
||||
### Criando Usuários Especializados de Ferramentas
|
||||
|
||||
Alguns agentes podem ser projetados para explorar certas ferramentas de maneira eficiente:
|
||||
|
||||
```yaml
|
||||
role: "Data Analysis Specialist"
|
||||
goal: "Derive meaningful insights from complex datasets through statistical analysis"
|
||||
backstory: "With a background in data science, you excel at working with structured and unstructured data..."
|
||||
tools: [PythonREPLTool, DataVisualizationTool, CSVAnalysisTool]
|
||||
```
|
||||
|
||||
### Personalizando Agentes para Capacidades do LLM
|
||||
|
||||
Diferentes LLMs têm pontos fortes distintos. Projete seus agentes levando essas capacidades em conta:
|
||||
|
||||
```yaml
|
||||
# For complex reasoning tasks
|
||||
analyst:
|
||||
role: "Data Insights Analyst"
|
||||
goal: "..."
|
||||
backstory: "..."
|
||||
llm: openai/gpt-4o
|
||||
|
||||
# For creative content
|
||||
writer:
|
||||
role: "Creative Content Writer"
|
||||
goal: "..."
|
||||
backstory: "..."
|
||||
llm: anthropic/claude-3-opus
|
||||
```
|
||||
|
||||
## Testando e Iterando no Design de Agentes
|
||||
|
||||
A construção de agentes geralmente é um processo iterativo. Veja como colocar em prática:
|
||||
|
||||
1. **Comece com um protótipo**: Crie uma definição inicial do agente
|
||||
2. **Teste com tarefas de exemplo**: Avalie o desempenho em tarefas representativas
|
||||
3. **Analise os resultados**: Identifique pontos fortes e fracos
|
||||
4. **Refine a definição**: Ajuste papel, objetivo e histórico conforme suas observações
|
||||
5. **Teste em colaboração**: Avalie como o agente se sai em conjunto no crew
|
||||
|
||||
## Conclusão
|
||||
|
||||
Criar agentes eficazes é tanto arte quanto ciência. Ao definir cuidadosamente papéis, objetivos e históricos alinhados às suas necessidades, e combinar isso com tarefas bem projetadas, você constrói colaboradores de IA especializados capazes de gerar resultados excepcionais.
|
||||
|
||||
Lembre-se de que o design de agentes e tarefas é um processo iterativo. Comece com essas boas práticas, observe os agentes em ação e refine sua abordagem conforme necessário. E sempre tenha em mente a regra 80/20 – concentre a maior parte do esforço em criar tarefas claras e focadas para tirar o melhor de seus agentes.
|
||||
|
||||
<Check>
|
||||
Parabéns! Agora você entende os princípios e práticas do design eficaz de agentes. Aplique estas técnicas para criar agentes poderosos e especializados que trabalham juntos perfeitamente e realizam tarefas complexas.
|
||||
</Check>
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
- Experimente diferentes configurações de agentes para o seu caso de uso
|
||||
- Aprenda sobre [como construir seu primeiro crew](/pt-BR/guides/crews/first-crew) para ver como agentes trabalham juntos
|
||||
- Explore os [CrewAI Flows](/pt-BR/guides/flows/first-flow) para uma orquestração mais avançada
|
||||
503
docs/pt-BR/guides/concepts/evaluating-use-cases.mdx
Normal file
503
docs/pt-BR/guides/concepts/evaluating-use-cases.mdx
Normal file
@@ -0,0 +1,503 @@
|
||||
---
|
||||
title: Avaliando Casos de Uso para CrewAI
|
||||
description: Aprenda a avaliar as necessidades da sua aplicação de IA e escolher a abordagem certa entre Crews e Flows com base nos requisitos de complexidade e precisão.
|
||||
icon: scale-balanced
|
||||
---
|
||||
|
||||
## Entendendo o Framework de Decisão
|
||||
|
||||
Ao construir aplicações de IA com CrewAI, uma das decisões mais importantes que você tomará é escolher a abordagem correta para o seu caso de uso específico. Você deve usar uma Crew? Um Flow? Uma combinação dos dois? Este guia vai ajudar você a avaliar seus requisitos e tomar decisões arquitetônicas embasadas.
|
||||
|
||||
No centro dessa decisão está o entendimento da relação entre **complexidade** e **precisão** em sua aplicação:
|
||||
|
||||
<Frame caption="Matriz de Complexidade vs. Precisão para Aplicações CrewAI">
|
||||
<img src="/images/complexity_precision.png" alt="Matriz de Complexidade vs. Precisão" />
|
||||
</Frame>
|
||||
|
||||
Essa matriz ajuda a visualizar como diferentes abordagens se alinham com os requisitos variados de complexidade e precisão. Vamos explorar o significado de cada quadrante e como isso orienta suas escolhas arquiteturais.
|
||||
|
||||
## Explicando a Matriz Complexidade-Precisão
|
||||
|
||||
### O que é Complexidade?
|
||||
|
||||
No contexto das aplicações CrewAI, **complexidade** refere-se a:
|
||||
|
||||
- O número de etapas ou operações distintas necessárias
|
||||
- A diversidade de tarefas que precisam ser realizadas
|
||||
- As interdependências entre diferentes componentes
|
||||
- A necessidade de lógica condicional e ramificações
|
||||
- A sofisticação do fluxo de trabalho como um todo
|
||||
|
||||
### O que é Precisão?
|
||||
|
||||
**Precisão** nesse contexto refere-se a:
|
||||
|
||||
- O grau de exatidão exigido no resultado final
|
||||
- A necessidade de resultados estruturados e previsíveis
|
||||
- A importância da reprodutibilidade
|
||||
- O nível de controle necessário sobre cada etapa
|
||||
- A tolerância à variação nos resultados
|
||||
|
||||
### Os Quatro Quadrantes
|
||||
|
||||
#### 1. Baixa Complexidade, Baixa Precisão
|
||||
|
||||
**Características:**
|
||||
- Tarefas simples e diretas
|
||||
- Tolerância a alguma variação nos resultados
|
||||
- Número limitado de etapas
|
||||
- Aplicações criativas ou exploratórias
|
||||
|
||||
**Abordagem Recomendada:** Crews simples com poucos agentes
|
||||
|
||||
**Exemplos de Casos de Uso:**
|
||||
- Geração básica de conteúdo
|
||||
- Brainstorming de ideias
|
||||
- Tarefas simples de sumarização
|
||||
- Assistência à escrita criativa
|
||||
|
||||
#### 2. Baixa Complexidade, Alta Precisão
|
||||
|
||||
**Características:**
|
||||
- Fluxos de trabalho simples que exigem resultados exatos e estruturados
|
||||
- Necessidade de resultados reproduzíveis
|
||||
- Poucas etapas, mas alto requisito de precisão
|
||||
- Frequentemente envolve processamento ou transformação de dados
|
||||
|
||||
**Abordagem Recomendada:** Flows com chamadas diretas a LLM ou Crews simples com saídas estruturadas
|
||||
|
||||
**Exemplos de Casos de Uso:**
|
||||
- Extração e transformação de dados
|
||||
- Preenchimento e validação de formulários
|
||||
- Geração estruturada de conteúdo (JSON, XML)
|
||||
- Tarefas simples de classificação
|
||||
|
||||
#### 3. Alta Complexidade, Baixa Precisão
|
||||
|
||||
**Características:**
|
||||
- Processos multiestágio com muitas etapas
|
||||
- Saídas criativas ou exploratórias
|
||||
- Interações complexas entre componentes
|
||||
- Tolerância à variação nos resultados finais
|
||||
|
||||
**Abordagem Recomendada:** Crews complexas com múltiplos agentes especializados
|
||||
|
||||
**Exemplos de Casos de Uso:**
|
||||
- Pesquisa e análise
|
||||
- Pipelines de criação de conteúdo
|
||||
- Análise exploratória de dados
|
||||
- Solução criativa de problemas
|
||||
|
||||
#### 4. Alta Complexidade, Alta Precisão
|
||||
|
||||
**Características:**
|
||||
- Fluxos de trabalho complexos que requerem saídas estruturadas
|
||||
- Múltiplas etapas interdependentes com rígida exigência de precisão
|
||||
- Necessidade tanto de processamento sofisticado quanto de resultados precisos
|
||||
- Frequentemente aplicações críticas
|
||||
|
||||
**Abordagem Recomendada:** Flows orquestrando múltiplas Crews com etapas de validação
|
||||
|
||||
**Exemplos de Casos de Uso:**
|
||||
- Sistemas corporativos de suporte à decisão
|
||||
- Pipelines complexos de processamento de dados
|
||||
- Processamento de documentos em múltiplos estágios
|
||||
- Aplicações em indústrias reguladas
|
||||
|
||||
## Escolhendo Entre Crews e Flows
|
||||
|
||||
### Quando Escolher Crews
|
||||
|
||||
Crews são ideais quando:
|
||||
|
||||
1. **Você precisa de inteligência colaborativa** - Múltiplos agentes com especializações diferentes precisam trabalhar juntos
|
||||
2. **O problema requer pensamento emergente** - A solução se beneficia de diferentes perspectivas e abordagens
|
||||
3. **A tarefa é principalmente criativa ou analítica** - O trabalho envolve pesquisa, criação de conteúdo ou análise
|
||||
4. **Você valoriza adaptabilidade mais do que estrutura rígida** - O fluxo de trabalho pode se beneficiar da autonomia dos agentes
|
||||
5. **O formato da saída pode ser um pouco flexível** - Alguma variação na estrutura do resultado é aceitável
|
||||
|
||||
```python
|
||||
# Example: Research Crew for market analysis
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
|
||||
# Create specialized agents
|
||||
researcher = Agent(
|
||||
role="Market Research Specialist",
|
||||
goal="Find comprehensive market data on emerging technologies",
|
||||
backstory="You are an expert at discovering market trends and gathering data."
|
||||
)
|
||||
|
||||
analyst = Agent(
|
||||
role="Market Analyst",
|
||||
goal="Analyze market data and identify key opportunities",
|
||||
backstory="You excel at interpreting market data and spotting valuable insights."
|
||||
)
|
||||
|
||||
# Define their tasks
|
||||
research_task = Task(
|
||||
description="Research the current market landscape for AI-powered healthcare solutions",
|
||||
expected_output="Comprehensive market data including key players, market size, and growth trends",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
analysis_task = Task(
|
||||
description="Analyze the market data and identify the top 3 investment opportunities",
|
||||
expected_output="Analysis report with 3 recommended investment opportunities and rationale",
|
||||
agent=analyst,
|
||||
context=[research_task]
|
||||
)
|
||||
|
||||
# Create the crew
|
||||
market_analysis_crew = Crew(
|
||||
agents=[researcher, analyst],
|
||||
tasks=[research_task, analysis_task],
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Run the crew
|
||||
result = market_analysis_crew.kickoff()
|
||||
```
|
||||
|
||||
### Quando Escolher Flows
|
||||
|
||||
Flows são ideais quando:
|
||||
|
||||
1. **Você precisa de controle preciso da execução** - O fluxo de trabalho exige sequenciamento exato e gerenciamento de estado
|
||||
2. **A aplicação tem requisitos complexos de estado** - Você precisa manter e transformar estado ao longo de múltiplas etapas
|
||||
3. **Você precisa de saídas estruturadas e previsíveis** - A aplicação exige resultados consistentes e formatados
|
||||
4. **O fluxo de trabalho envolve lógica condicional** - Caminhos diferentes precisam ser seguidos com base em resultados intermediários
|
||||
5. **Você precisa combinar IA com código procedural** - A solução demanda tanto capacidades de IA quanto programação tradicional
|
||||
|
||||
```python
|
||||
# Example: Customer Support Flow with structured processing
|
||||
from crewai.flow.flow import Flow, listen, router, start
|
||||
from pydantic import BaseModel
|
||||
from typing import List, Dict
|
||||
|
||||
# Define structured state
|
||||
class SupportTicketState(BaseModel):
|
||||
ticket_id: str = ""
|
||||
customer_name: str = ""
|
||||
issue_description: str = ""
|
||||
category: str = ""
|
||||
priority: str = "medium"
|
||||
resolution: str = ""
|
||||
satisfaction_score: int = 0
|
||||
|
||||
class CustomerSupportFlow(Flow[SupportTicketState]):
|
||||
@start()
|
||||
def receive_ticket(self):
|
||||
# In a real app, this might come from an API
|
||||
self.state.ticket_id = "TKT-12345"
|
||||
self.state.customer_name = "Alex Johnson"
|
||||
self.state.issue_description = "Unable to access premium features after payment"
|
||||
return "Ticket received"
|
||||
|
||||
@listen(receive_ticket)
|
||||
def categorize_ticket(self, _):
|
||||
# Use a direct LLM call for categorization
|
||||
from crewai import LLM
|
||||
llm = LLM(model="openai/gpt-4o-mini")
|
||||
|
||||
prompt = f"""
|
||||
Categorize the following customer support issue into one of these categories:
|
||||
- Billing
|
||||
- Account Access
|
||||
- Technical Issue
|
||||
- Feature Request
|
||||
- Other
|
||||
|
||||
Issue: {self.state.issue_description}
|
||||
|
||||
Return only the category name.
|
||||
"""
|
||||
|
||||
self.state.category = llm.call(prompt).strip()
|
||||
return self.state.category
|
||||
|
||||
@router(categorize_ticket)
|
||||
def route_by_category(self, category):
|
||||
# Route to different handlers based on category
|
||||
return category.lower().replace(" ", "_")
|
||||
|
||||
@listen("billing")
|
||||
def handle_billing_issue(self):
|
||||
# Handle billing-specific logic
|
||||
self.state.priority = "high"
|
||||
# More billing-specific processing...
|
||||
return "Billing issue handled"
|
||||
|
||||
@listen("account_access")
|
||||
def handle_access_issue(self):
|
||||
# Handle access-specific logic
|
||||
self.state.priority = "high"
|
||||
# More access-specific processing...
|
||||
return "Access issue handled"
|
||||
|
||||
# Additional category handlers...
|
||||
|
||||
@listen("billing", "account_access", "technical_issue", "feature_request", "other")
|
||||
def resolve_ticket(self, resolution_info):
|
||||
# Final resolution step
|
||||
self.state.resolution = f"Issue resolved: {resolution_info}"
|
||||
return self.state.resolution
|
||||
|
||||
# Run the flow
|
||||
support_flow = CustomerSupportFlow()
|
||||
result = support_flow.kickoff()
|
||||
```
|
||||
|
||||
### Quando Combinar Crews e Flows
|
||||
|
||||
As aplicações mais sofisticadas frequentemente se beneficiam da combinação de Crews e Flows:
|
||||
|
||||
1. **Processos complexos em múltiplos estágios** - Use Flows para orquestrar o processo geral e Crews para sub-tarefas complexas
|
||||
2. **Aplicações que exigem criatividade e estrutura** - Use Crews para tarefas criativas e Flows para processamento estruturado
|
||||
3. **Aplicações corporativas de IA** - Use Flows para gerenciar estado e fluxo de processo enquanto aproveita Crews para tarefas especializadas
|
||||
|
||||
```python
|
||||
# Example: Content Production Pipeline combining Crews and Flows
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from pydantic import BaseModel
|
||||
from typing import List, Dict
|
||||
|
||||
class ContentState(BaseModel):
|
||||
topic: str = ""
|
||||
target_audience: str = ""
|
||||
content_type: str = ""
|
||||
outline: Dict = {}
|
||||
draft_content: str = ""
|
||||
final_content: str = ""
|
||||
seo_score: int = 0
|
||||
|
||||
class ContentProductionFlow(Flow[ContentState]):
|
||||
@start()
|
||||
def initialize_project(self):
|
||||
# Set initial parameters
|
||||
self.state.topic = "Sustainable Investing"
|
||||
self.state.target_audience = "Millennial Investors"
|
||||
self.state.content_type = "Blog Post"
|
||||
return "Project initialized"
|
||||
|
||||
@listen(initialize_project)
|
||||
def create_outline(self, _):
|
||||
# Use a research crew to create an outline
|
||||
researcher = Agent(
|
||||
role="Content Researcher",
|
||||
goal=f"Research {self.state.topic} for {self.state.target_audience}",
|
||||
backstory="You are an expert researcher with deep knowledge of content creation."
|
||||
)
|
||||
|
||||
outliner = Agent(
|
||||
role="Content Strategist",
|
||||
goal=f"Create an engaging outline for a {self.state.content_type}",
|
||||
backstory="You excel at structuring content for maximum engagement."
|
||||
)
|
||||
|
||||
research_task = Task(
|
||||
description=f"Research {self.state.topic} focusing on what would interest {self.state.target_audience}",
|
||||
expected_output="Comprehensive research notes with key points and statistics",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
outline_task = Task(
|
||||
description=f"Create an outline for a {self.state.content_type} about {self.state.topic}",
|
||||
expected_output="Detailed content outline with sections and key points",
|
||||
agent=outliner,
|
||||
context=[research_task]
|
||||
)
|
||||
|
||||
outline_crew = Crew(
|
||||
agents=[researcher, outliner],
|
||||
tasks=[research_task, outline_task],
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Run the crew and store the result
|
||||
result = outline_crew.kickoff()
|
||||
|
||||
# Parse the outline (in a real app, you might use a more robust parsing approach)
|
||||
import json
|
||||
try:
|
||||
self.state.outline = json.loads(result.raw)
|
||||
except:
|
||||
# Fallback if not valid JSON
|
||||
self.state.outline = {"sections": result.raw}
|
||||
|
||||
return "Outline created"
|
||||
|
||||
@listen(create_outline)
|
||||
def write_content(self, _):
|
||||
# Use a writing crew to create the content
|
||||
writer = Agent(
|
||||
role="Content Writer",
|
||||
goal=f"Write engaging content for {self.state.target_audience}",
|
||||
backstory="You are a skilled writer who creates compelling content."
|
||||
)
|
||||
|
||||
editor = Agent(
|
||||
role="Content Editor",
|
||||
goal="Ensure content is polished, accurate, and engaging",
|
||||
backstory="You have a keen eye for detail and a talent for improving content."
|
||||
)
|
||||
|
||||
writing_task = Task(
|
||||
description=f"Write a {self.state.content_type} about {self.state.topic} following this outline: {self.state.outline}",
|
||||
expected_output="Complete draft content in markdown format",
|
||||
agent=writer
|
||||
)
|
||||
|
||||
editing_task = Task(
|
||||
description="Edit and improve the draft content for clarity, engagement, and accuracy",
|
||||
expected_output="Polished final content in markdown format",
|
||||
agent=editor,
|
||||
context=[writing_task]
|
||||
)
|
||||
|
||||
writing_crew = Crew(
|
||||
agents=[writer, editor],
|
||||
tasks=[writing_task, editing_task],
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Run the crew and store the result
|
||||
result = writing_crew.kickoff()
|
||||
self.state.final_content = result.raw
|
||||
|
||||
return "Content created"
|
||||
|
||||
@listen(write_content)
|
||||
def optimize_for_seo(self, _):
|
||||
# Use a direct LLM call for SEO optimization
|
||||
from crewai import LLM
|
||||
llm = LLM(model="openai/gpt-4o-mini")
|
||||
|
||||
prompt = f"""
|
||||
Analyze this content for SEO effectiveness for the keyword "{self.state.topic}".
|
||||
Rate it on a scale of 1-100 and provide 3 specific recommendations for improvement.
|
||||
|
||||
Content: {self.state.final_content[:1000]}... (truncated for brevity)
|
||||
|
||||
Format your response as JSON with the following structure:
|
||||
{{
|
||||
"score": 85,
|
||||
"recommendations": [
|
||||
"Recommendation 1",
|
||||
"Recommendation 2",
|
||||
"Recommendation 3"
|
||||
]
|
||||
}}
|
||||
"""
|
||||
|
||||
seo_analysis = llm.call(prompt)
|
||||
|
||||
# Parse the SEO analysis
|
||||
import json
|
||||
try:
|
||||
analysis = json.loads(seo_analysis)
|
||||
self.state.seo_score = analysis.get("score", 0)
|
||||
return analysis
|
||||
except:
|
||||
self.state.seo_score = 50
|
||||
return {"score": 50, "recommendations": ["Unable to parse SEO analysis"]}
|
||||
|
||||
# Run the flow
|
||||
content_flow = ContentProductionFlow()
|
||||
result = content_flow.kickoff()
|
||||
```
|
||||
|
||||
## Framework Prático de Avaliação
|
||||
|
||||
Para determinar a abordagem certa para seu caso de uso específico, siga este framework passo a passo:
|
||||
|
||||
### Passo 1: Avalie a Complexidade
|
||||
|
||||
Classifique a complexidade do seu aplicativo numa escala de 1-10 considerando:
|
||||
|
||||
1. **Número de etapas**: Quantas operações distintas são necessárias?
|
||||
- 1-3 etapas: Baixa complexidade (1-3)
|
||||
- 4-7 etapas: Média complexidade (4-7)
|
||||
- 8+ etapas: Alta complexidade (8-10)
|
||||
|
||||
2. **Interdependências**: Quão interligadas estão as partes diferentes?
|
||||
- Poucas dependências: Baixa complexidade (1-3)
|
||||
- Algumas dependências: Média complexidade (4-7)
|
||||
- Muitas dependências complexas: Alta complexidade (8-10)
|
||||
|
||||
3. **Lógica condicional**: Quanto de ramificação e tomada de decisão é necessário?
|
||||
- Processo linear: Baixa complexidade (1-3)
|
||||
- Alguma ramificação: Média complexidade (4-7)
|
||||
- Árvores de decisão complexas: Alta complexidade (8-10)
|
||||
|
||||
4. **Conhecimento de domínio**: Quão especializado deve ser o conhecimento requerido?
|
||||
- Conhecimento geral: Baixa complexidade (1-3)
|
||||
- Algum conhecimento especializado: Média complexidade (4-7)
|
||||
- Grande especialização em múltiplos domínios: Alta complexidade (8-10)
|
||||
|
||||
Calcule a média das pontuações para determinar sua complexidade geral.
|
||||
|
||||
### Passo 2: Avalie os Requisitos de Precisão
|
||||
|
||||
Classifique seus requisitos de precisão numa escala de 1-10 considerando:
|
||||
|
||||
1. **Estrutura da saída**: Quão estruturado o resultado deve ser?
|
||||
- Texto livre: Baixa precisão (1-3)
|
||||
- Semi-estruturado: Média precisão (4-7)
|
||||
- Estritamente formatado (JSON, XML): Alta precisão (8-10)
|
||||
|
||||
2. **Necessidade de exatidão**: Qual a importância da precisão factual?
|
||||
- Conteúdo criativo: Baixa precisão (1-3)
|
||||
- Conteúdo informacional: Média precisão (4-7)
|
||||
- Informação crítica: Alta precisão (8-10)
|
||||
|
||||
3. **Reprodutibilidade**: Quão consistentes devem ser os resultados entre execuções?
|
||||
- Variação aceitável: Baixa precisão (1-3)
|
||||
- Alguma consistência necessária: Média precisão (4-7)
|
||||
- Exata reprodutibilidade: Alta precisão (8-10)
|
||||
|
||||
4. **Tolerância a erros**: Qual o impacto de erros?
|
||||
- Baixo impacto: Baixa precisão (1-3)
|
||||
- Impacto moderado: Média precisão (4-7)
|
||||
- Alto impacto: Alta precisão (8-10)
|
||||
|
||||
Calcule a média das pontuações para determinar seu requisito geral de precisão.
|
||||
|
||||
### Passo 3: Mapeie na Matriz
|
||||
|
||||
Plote as pontuações de complexidade e precisão na matriz:
|
||||
|
||||
- **Baixa Complexidade (1-4), Baixa Precisão (1-4)**: Crews simples
|
||||
- **Baixa Complexidade (1-4), Alta Precisão (5-10)**: Flows com chamadas diretas a LLM
|
||||
- **Alta Complexidade (5-10), Baixa Precisão (1-4)**: Crews complexas
|
||||
- **Alta Complexidade (5-10), Alta Precisão (5-10)**: Flows orquestrando Crews
|
||||
|
||||
### Passo 4: Considere Fatores Adicionais
|
||||
|
||||
Além de complexidade e precisão, considere:
|
||||
|
||||
1. **Tempo de desenvolvimento**: Crews costumam ser mais rápidas para prototipar
|
||||
2. **Necessidades de manutenção**: Flows proporcionam melhor manutenção a longo prazo
|
||||
3. **Expertise do time**: Considere a familiaridade de sua equipe com as abordagens
|
||||
4. **Requisitos de escalabilidade**: Flows normalmente escalam melhor para aplicações complexas
|
||||
5. **Necessidades de integração**: Considere como a solução se integrará aos sistemas existentes
|
||||
|
||||
## Conclusão
|
||||
|
||||
Escolher entre Crews e Flows — ou combiná-los — é uma decisão arquitetônica crítica que impacta a efetividade, manutenibilidade e escalabilidade da sua aplicação CrewAI. Ao avaliar seu caso de uso nas dimensões de complexidade e precisão, você toma decisões inteligentes que alinham-se aos seus requisitos.
|
||||
|
||||
Lembre-se de que a melhor abordagem geralmente evolui na medida em que sua aplicação amadurece. Comece com a solução mais simples que atenda às suas necessidades e esteja preparado para refinar sua arquitetura conforme for ganhando experiência e seus requisitos se tornarem mais claros.
|
||||
|
||||
<Check>
|
||||
Agora você tem um framework para avaliar casos de uso CrewAI e escolher a abordagem certa de acordo com requisitos de complexidade e precisão. Isso vai ajudar você a construir aplicações de IA mais eficientes, de fácil manutenção e escaláveis.
|
||||
</Check>
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
- Saiba mais sobre [como criar agentes eficazes](/pt-BR/guides/agents/crafting-effective-agents)
|
||||
- Explore [como construir sua primeira crew](/pt-BR/guides/crews/first-crew)
|
||||
- Aprofunde-se em [gerenciamento de estado em flows](/pt-BR/guides/flows/mastering-flow-state)
|
||||
- Confira os [conceitos centrais](/pt-BR/concepts/agents) para um entendimento mais aprofundado
|
||||
392
docs/pt-BR/guides/crews/first-crew.mdx
Normal file
392
docs/pt-BR/guides/crews/first-crew.mdx
Normal file
@@ -0,0 +1,392 @@
|
||||
---
|
||||
title: Monte sua Primeira Crew
|
||||
description: Tutorial passo a passo para criar uma equipe colaborativa de IA que trabalha junta para resolver problemas complexos.
|
||||
icon: users-gear
|
||||
---
|
||||
|
||||
## Liberando o Poder da IA Colaborativa
|
||||
|
||||
Imagine ter uma equipe de agentes de IA especializados trabalhando juntos de forma harmoniosa para resolver problemas complexos, cada um contribuindo com suas habilidades únicas para alcançar um objetivo comum. Esse é o poder da CrewAI – um framework que permite criar sistemas colaborativos de IA que podem realizar tarefas muito além do que uma única IA conseguiria sozinha.
|
||||
|
||||
Neste guia, vamos criar uma crew de pesquisa que irá nos ajudar a pesquisar e analisar um tema, e então criar um relatório abrangente. Este exemplo prático demonstra como agentes de IA podem colaborar para realizar tarefas complexas, mas é apenas o começo do que é possível com a CrewAI.
|
||||
|
||||
### O que Você Vai Construir e Aprender
|
||||
|
||||
Ao final deste guia, você terá:
|
||||
|
||||
1. **Criado uma equipe de pesquisa em IA especializada** com papéis e responsabilidades distintas
|
||||
2. **Orquestrado a colaboração** entre múltiplos agentes de IA
|
||||
3. **Automatizado um fluxo de trabalho complexo** que envolve coleta de informações, análise e geração de relatórios
|
||||
4. **Desenvolvido habilidades fundamentais** que podem ser aplicadas em projetos mais ambiciosos
|
||||
|
||||
Embora estejamos criando uma crew de pesquisa simples neste guia, os mesmos padrões e técnicas podem ser aplicados para criar equipes muito mais sofisticadas para tarefas como:
|
||||
|
||||
- Criação de conteúdo em múltiplas etapas com redatores, editores e checadores de fatos especializados
|
||||
- Sistemas de atendimento ao cliente complexos com agentes de suporte em diferentes níveis
|
||||
- Analistas de negócios autônomos que coletam dados, criam visualizações e geram insights
|
||||
- Equipes de desenvolvimento de produto que idealizam, projetam e planejam a implementação
|
||||
|
||||
Vamos começar a construir sua primeira crew!
|
||||
|
||||
### Pré-requisitos
|
||||
|
||||
Antes de começar, certifique-se de que você:
|
||||
|
||||
1. Instalou a CrewAI seguindo o [guia de instalação](/pt-BR/installation)
|
||||
2. Configurou sua chave de API de LLM no ambiente, conforme o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm)
|
||||
3. Tem conhecimento básico de Python
|
||||
|
||||
## Passo 1: Crie um Novo Projeto CrewAI
|
||||
|
||||
Primeiro, vamos criar um novo projeto CrewAI usando a CLI. Este comando irá configurar toda a estrutura do projeto com os arquivos necessários, permitindo que você foque em definir seus agentes e suas tarefas, em vez de se preocupar com código boilerplate.
|
||||
|
||||
```bash
|
||||
crewai create crew research_crew
|
||||
cd research_crew
|
||||
```
|
||||
|
||||
Isso irá gerar um projeto com a estrutura básica necessária para sua crew. A CLI cria automaticamente:
|
||||
|
||||
- Um diretório de projeto com os arquivos necessários
|
||||
- Arquivos de configuração para agentes e tarefas
|
||||
- Uma implementação básica da crew
|
||||
- Um script principal para rodar a crew
|
||||
|
||||
<Frame caption="CrewAI Framework Overview">
|
||||
<img src="/images/crews.png" alt="CrewAI Framework Overview" />
|
||||
</Frame>
|
||||
|
||||
|
||||
## Passo 2: Explore a Estrutura do Projeto
|
||||
|
||||
Vamos dedicar um momento para entender a estrutura do projeto criada pela CLI. A CrewAI segue boas práticas para projetos Python, tornando fácil manter e estender seu código à medida que suas crews se tornam mais complexas.
|
||||
|
||||
```
|
||||
research_crew/
|
||||
├── .gitignore
|
||||
├── pyproject.toml
|
||||
├── README.md
|
||||
├── .env
|
||||
└── src/
|
||||
└── research_crew/
|
||||
├── __init__.py
|
||||
├── main.py
|
||||
├── crew.py
|
||||
├── tools/
|
||||
│ ├── custom_tool.py
|
||||
│ └── __init__.py
|
||||
└── config/
|
||||
├── agents.yaml
|
||||
└── tasks.yaml
|
||||
```
|
||||
|
||||
Esta estrutura segue as melhores práticas para projetos Python e facilita a organização do seu código. A separação dos arquivos de configuração (em YAML) do código de implementação (em Python) permite modificar o comportamento da sua crew sem alterar o código subjacente.
|
||||
|
||||
## Passo 3: Configure seus Agentes
|
||||
|
||||
Agora vem a parte divertida – definir seus agentes de IA! Na CrewAI, agentes são entidades especializadas com papéis, objetivos e históricos específicos que moldam seu comportamento. Pense neles como personagens em uma peça, cada um com sua personalidade e propósito próprios.
|
||||
|
||||
Para nossa crew de pesquisa, vamos criar dois agentes:
|
||||
1. Um **pesquisador** que é especialista em encontrar e organizar informações
|
||||
2. Um **analista** que pode interpretar os resultados da pesquisa e criar relatórios perspicazes
|
||||
|
||||
Vamos modificar o arquivo `agents.yaml` para definir esses agentes especializados. Certifique-se de
|
||||
definir `llm` para o provedor que você está utilizando.
|
||||
|
||||
```yaml
|
||||
# src/research_crew/config/agents.yaml
|
||||
researcher:
|
||||
role: >
|
||||
Especialista Sênior em Pesquisa para {topic}
|
||||
goal: >
|
||||
Encontrar informações abrangentes e precisas sobre {topic}
|
||||
com foco em desenvolvimentos recentes e insights chave
|
||||
backstory: >
|
||||
Você é um especialista em pesquisa experiente com talento para
|
||||
encontrar informações relevantes de diversas fontes. Você se destaca em
|
||||
organizar informações de forma clara e estruturada, tornando temas complexos acessíveis para outros.
|
||||
llm: provider/model-id # ex: openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
|
||||
|
||||
analyst:
|
||||
role: >
|
||||
Analista de Dados e Redator de Relatórios para {topic}
|
||||
goal: >
|
||||
Analisar os resultados da pesquisa e criar um relatório abrangente e bem estruturado
|
||||
que apresente os insights de forma clara e envolvente
|
||||
backstory: >
|
||||
Você é um analista habilidoso com experiência em interpretação de dados
|
||||
e redação técnica. Tem talento para identificar padrões
|
||||
e extrair insights relevantes dos dados de pesquisa, comunicando esses insights de forma eficaz por meio de relatórios bem elaborados.
|
||||
llm: provider/model-id # ex: openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
|
||||
```
|
||||
|
||||
Perceba como cada agente tem um papel, objetivo e histórico distintos. Esses elementos não são apenas descritivos – eles efetivamente moldam como o agente aborda suas tarefas. Ao criar cuidadosamente esses detalhes, você pode ter agentes com habilidades e perspectivas que se complementam.
|
||||
|
||||
## Passo 4: Defina suas Tarefas
|
||||
|
||||
Com nossos agentes definidos, agora precisamos atribuir tarefas específicas para eles realizarem. Tarefas na CrewAI representam o trabalho concreto que os agentes irão executar, com instruções detalhadas e saídas esperadas.
|
||||
|
||||
Para nossa crew de pesquisa, vamos definir duas tarefas principais:
|
||||
1. Uma **tarefa de pesquisa** para coletar informações abrangentes
|
||||
2. Uma **tarefa de análise** para criar um relatório com insights
|
||||
|
||||
Vamos modificar o arquivo `tasks.yaml`:
|
||||
|
||||
```yaml
|
||||
# src/research_crew/config/tasks.yaml
|
||||
research_task:
|
||||
description: >
|
||||
Realize uma pesquisa aprofundada sobre {topic}. Foque em:
|
||||
1. Conceitos e definições chave
|
||||
2. Desenvolvimento histórico e tendências recentes
|
||||
3. Principais desafios e oportunidades
|
||||
4. Aplicações relevantes ou estudos de caso
|
||||
5. Perspectivas futuras e novos desenvolvimentos
|
||||
|
||||
Certifique-se de organizar seus achados em um formato estruturado, com seções claras.
|
||||
expected_output: >
|
||||
Um documento de pesquisa abrangente com seções bem organizadas cobrindo
|
||||
todos os aspectos solicitados de {topic}. Inclua fatos, números
|
||||
e exemplos específicos sempre que possível.
|
||||
agent: researcher
|
||||
|
||||
analysis_task:
|
||||
description: >
|
||||
Analise os resultados da pesquisa e crie um relatório abrangente sobre {topic}.
|
||||
Seu relatório deve:
|
||||
1. Iniciar com um resumo executivo
|
||||
2. Incluir todas as informações relevantes da pesquisa
|
||||
3. Oferecer uma análise perspicaz de tendências e padrões
|
||||
4. Apresentar recomendações ou considerações futuras
|
||||
5. Estar formatado de forma profissional, clara e com títulos bem definidos
|
||||
expected_output: >
|
||||
Um relatório profissional, polido e estruturado sobre {topic} com apresentação dos resultados da pesquisa,
|
||||
acrescentando análise e insights. O relatório deve ser bem estruturado,
|
||||
incluindo resumo executivo, sessões principais e conclusão.
|
||||
agent: analyst
|
||||
context:
|
||||
- research_task
|
||||
output_file: output/report.md
|
||||
```
|
||||
|
||||
Note o campo `context` na tarefa de análise – esse é um recurso poderoso que permite ao analista acessar a saída da tarefa de pesquisa. Isso cria um fluxo de trabalho em que a informação circula naturalmente entre os agentes, como aconteceria em uma equipe humana.
|
||||
|
||||
## Passo 5: Configure sua Crew
|
||||
|
||||
Agora é hora de juntar tudo configurando nossa crew. A crew é o container que orquestra como os agentes trabalham juntos para completar as tarefas.
|
||||
|
||||
Vamos modificar o arquivo `crew.py`:
|
||||
|
||||
```python
|
||||
# src/research_crew/crew.py
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from crewai.project import CrewBase, agent, crew, task
|
||||
from crewai_tools import SerperDevTool
|
||||
from crewai.agents.agent_builder.base_agent import BaseAgent
|
||||
from typing import List
|
||||
|
||||
@CrewBase
|
||||
class ResearchCrew():
|
||||
"""Research crew for comprehensive topic analysis and reporting"""
|
||||
|
||||
agents: List[BaseAgent]
|
||||
tasks: List[Task]
|
||||
|
||||
@agent
|
||||
def researcher(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['researcher'], # type: ignore[index]
|
||||
verbose=True,
|
||||
tools=[SerperDevTool()]
|
||||
)
|
||||
|
||||
@agent
|
||||
def analyst(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['analyst'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
@task
|
||||
def research_task(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['research_task'] # type: ignore[index]
|
||||
)
|
||||
|
||||
@task
|
||||
def analysis_task(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['analysis_task'], # type: ignore[index]
|
||||
output_file='output/report.md'
|
||||
)
|
||||
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
"""Creates the research crew"""
|
||||
return Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
verbose=True,
|
||||
)
|
||||
```
|
||||
|
||||
Neste código, estamos:
|
||||
1. Criando o agente pesquisador e equipando-o com o SerperDevTool para buscas web
|
||||
2. Criando o agente analista
|
||||
3. Definindo as tarefas de pesquisa e análise
|
||||
4. Configurando a crew para executar as tarefas sequencialmente (o analista espera o pesquisador terminar)
|
||||
|
||||
É aqui que a mágica acontece – com poucas linhas de código, definimos um sistema colaborativo de IA onde agentes especializados trabalham juntos em um processo coordenado.
|
||||
|
||||
## Passo 6: Prepare seu Script Principal
|
||||
|
||||
Agora, vamos preparar o script principal que irá rodar nossa crew. É aqui que informamos o tema específico que queremos pesquisar.
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python
|
||||
# src/research_crew/main.py
|
||||
import os
|
||||
from research_crew.crew import ResearchCrew
|
||||
|
||||
# Crie o diretório de saída se não existir
|
||||
os.makedirs('output', exist_ok=True)
|
||||
|
||||
def run():
|
||||
"""
|
||||
Rodar a crew de pesquisa.
|
||||
"""
|
||||
inputs = {
|
||||
'topic': 'Inteligência Artificial na Saúde'
|
||||
}
|
||||
|
||||
# Criar e rodar a crew
|
||||
result = ResearchCrew().crew().kickoff(inputs=inputs)
|
||||
|
||||
# Imprimir o resultado
|
||||
print("\n\n=== RELATÓRIO FINAL ===\n\n")
|
||||
print(result.raw)
|
||||
|
||||
print("\n\nRelatório salvo em output/report.md")
|
||||
|
||||
if __name__ == "__main__":
|
||||
run()
|
||||
```
|
||||
|
||||
Este script prepara o ambiente, define o tema de pesquisa e inicia o trabalho da crew. O poder da CrewAI fica evidente em como esse código é simples – toda a complexidade do gerenciamento de múltiplos agentes de IA é tratada pelo framework.
|
||||
|
||||
## Passo 7: Defina suas Variáveis de Ambiente
|
||||
|
||||
Crie um arquivo `.env` na raiz do seu projeto com suas chaves de API:
|
||||
|
||||
```sh
|
||||
SERPER_API_KEY=sua_serper_api_key
|
||||
# Adicione a chave de API do seu provedor também.
|
||||
```
|
||||
|
||||
Confira o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm) para detalhes sobre como configurar o provedor de sua escolha. Você pode obter a chave da Serper em [Serper.dev](https://serper.dev/).
|
||||
|
||||
## Passo 8: Instale as Dependências
|
||||
|
||||
Instale as dependências necessárias usando a CLI da CrewAI:
|
||||
|
||||
```bash
|
||||
crewai install
|
||||
```
|
||||
|
||||
Este comando irá:
|
||||
1. Ler as dependências da configuração do seu projeto
|
||||
2. Criar um ambiente virtual se necessário
|
||||
3. Instalar todos os pacotes necessários
|
||||
|
||||
## Passo 9: Execute sua Crew
|
||||
|
||||
Agora chega o momento empolgante – é hora de rodar sua crew e assistir à colaboração de IA em ação!
|
||||
|
||||
```bash
|
||||
crewai run
|
||||
```
|
||||
|
||||
Ao rodar esse comando, você verá sua crew ganhando vida. O pesquisador irá coletar informações sobre o tema especificado, e o analista irá criar um relatório abrangente baseado nessa pesquisa. Você poderá acompanhar em tempo real o raciocínio, as ações e os resultados dos agentes à medida que colaboram para concluir as tarefas.
|
||||
|
||||
## Passo 10: Revise o Resultado
|
||||
|
||||
Após a conclusão do trabalho da crew, você encontrará o relatório final em `output/report.md`. O relatório incluirá:
|
||||
|
||||
1. Um resumo executivo
|
||||
2. Informações detalhadas sobre o tema
|
||||
3. Análises e insights
|
||||
4. Recomendações ou considerações futuras
|
||||
|
||||
Tire um momento para valorizar o que você realizou – você criou um sistema no qual múltiplos agentes de IA colaboraram em uma tarefa complexa, cada um contribuindo com suas habilidades especializadas para gerar um resultado maior do que qualquer agente conseguiria sozinho.
|
||||
|
||||
## Explorando Outros Comandos da CLI
|
||||
|
||||
A CrewAI oferece vários outros comandos úteis de CLI para trabalhar com crews:
|
||||
|
||||
```bash
|
||||
# Ver todos os comandos disponíveis
|
||||
crewai --help
|
||||
|
||||
# Rodar a crew
|
||||
crewai run
|
||||
|
||||
# Testar a crew
|
||||
crewai test
|
||||
|
||||
# Resetar as memórias da crew
|
||||
crewai reset-memories
|
||||
|
||||
# Repetir a partir de uma tarefa específica
|
||||
crewai replay -t <task_id>
|
||||
```
|
||||
|
||||
## O que Mais é Possível: Além da sua Primeira Crew
|
||||
|
||||
O que você construiu neste guia é só o começo. As habilidades e padrões aprendidos aqui podem ser aplicados para criar sistemas de IA cada vez mais sofisticados. Veja algumas maneiras de expandir sua crew de pesquisa básica:
|
||||
|
||||
### Expandindo sua Crew
|
||||
|
||||
Você pode adicionar mais agentes especializados à sua crew:
|
||||
- Um **checador de fatos** para verificar as informações encontradas
|
||||
- Um **visualizador de dados** para criar gráficos e tabelas
|
||||
- Um **especialista de domínio** com conhecimento aprofundado em uma área específica
|
||||
- Um **crítico** para identificar pontos fracos na análise
|
||||
|
||||
### Adicionando Ferramentas e Capacidades
|
||||
|
||||
Você pode potencializar seus agentes com ferramentas adicionais:
|
||||
- Ferramentas de navegação web para pesquisa em tempo real
|
||||
- Ferramentas para CSV ou bancos de dados para análise de dados
|
||||
- Ferramentas de execução de código para processamento de dados
|
||||
- Conexões de API com serviços externos
|
||||
|
||||
### Criando Fluxos de Trabalho Mais Complexos
|
||||
|
||||
Você pode implementar processos mais sofisticados:
|
||||
- Processos hierárquicos em que agentes gestores delegam para agentes
|
||||
- Processos iterativos com loops de feedback para refinamento
|
||||
- Processos paralelos onde múltiplos agentes trabalham simultaneamente
|
||||
- Processos dinâmicos que se adaptam a resultados intermediários
|
||||
|
||||
### Aplicando em Diferentes Domínios
|
||||
|
||||
Os mesmos padrões podem ser aplicados para criar crews para:
|
||||
- **Criação de conteúdo:** Redatores, editores, checadores de fatos e designers trabalhando juntos
|
||||
- **Atendimento ao cliente:** Agentes de triagem, especialistas e controle de qualidade atuando colaborativamente
|
||||
- **Desenvolvimento de produto:** Pesquisadores, designers e planejadores trabalhando em conjunto
|
||||
- **Análise de dados:** Coletores de dados, analistas e especialistas em visualização
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
Agora que você montou sua primeira crew, você pode:
|
||||
|
||||
1. Experimentar diferentes configurações e personalidades de agentes
|
||||
2. Testar estruturas de tarefas e fluxos de trabalho mais complexos
|
||||
3. Implementar ferramentas customizadas para dar novas capacidades aos agentes
|
||||
4. Aplicar sua crew em outros temas ou domínios de problemas
|
||||
5. Explorar [CrewAI Flows](/pt-BR/guides/flows/first-flow) para fluxos de trabalho avançados usando programação procedural
|
||||
|
||||
<Check>
|
||||
Parabéns! Você construiu com sucesso sua primeira crew com o CrewAI, capaz de pesquisar e analisar qualquer tema que desejar. Essa experiência fundamental lhe deu as habilidades para criar sistemas de IA cada vez mais sofisticados, aptos a encarar problemas complexos e de múltiplas etapas por meio da inteligência colaborativa.
|
||||
</Check>
|
||||
461
docs/pt-BR/guides/flows/first-flow.mdx
Normal file
461
docs/pt-BR/guides/flows/first-flow.mdx
Normal file
@@ -0,0 +1,461 @@
|
||||
---
|
||||
title: Construa Seu Primeiro Flow
|
||||
description: Aprenda como criar fluxos de trabalho estruturados e orientados a eventos com controle preciso sobre a execução.
|
||||
icon: diagram-project
|
||||
---
|
||||
|
||||
## Assumindo o Controle de Workflows de IA com Flows
|
||||
|
||||
Os Flows do CrewAI representam o próximo nível em orquestração de IA – combinando o poder colaborativo de equipes de agentes de IA com a precisão e flexibilidade da programação procedural. Enquanto os crews se destacam em colaboração de agentes, os flows dão a você controle detalhado sobre exatamente como e quando diferentes componentes do seu sistema de IA interagem.
|
||||
|
||||
Neste guia, vamos percorrer a criação de um poderoso CrewAI Flow que gera um guia de aprendizado abrangente sobre qualquer tema. Este tutorial demonstrará como os Flows oferecem controle estruturado e orientado a eventos sobre seus workflows de IA ao combinar código regular, chamadas diretas a LLM e processamento baseado em crews.
|
||||
|
||||
### O Que Torna os Flows Poderosos
|
||||
|
||||
Com flows, você pode:
|
||||
|
||||
1. **Combinar diferentes padrões de interação com IA** – Use crews para tarefas colaborativas complexas, chamadas diretas às LLMs para operações mais simples, e código regular para lógica procedural.
|
||||
2. **Construir sistemas orientados a eventos** – Defina como os componentes respondem a eventos e mudanças de dados específicos.
|
||||
3. **Manter estado entre componentes** – Compartilhe e transforme dados entre diferentes partes da sua aplicação.
|
||||
4. **Integrar com sistemas externos** – Conecte seu fluxo de trabalho de IA com bancos de dados, APIs e interfaces de usuário de forma transparente.
|
||||
5. **Criar caminhos de execução complexos** – Projete ramificações condicionais, processamento paralelo e workflows dinâmicos.
|
||||
|
||||
### O Que Você Vai Construir e Aprender
|
||||
|
||||
Ao final deste guia, você terá:
|
||||
|
||||
1. **Criado um sistema sofisticado de geração de conteúdo** que combina entrada do usuário, planejamento por IA e criação de conteúdo multiagente.
|
||||
2. **Orquestrado o fluxo de informações** entre diferentes componentes do seu sistema.
|
||||
3. **Implementado uma arquitetura orientada a eventos** onde cada etapa responde à conclusão das etapas anteriores.
|
||||
4. **Construído uma base para aplicações de IA mais complexas** que você pode expandir e personalizar.
|
||||
|
||||
Este flow de criação de guia demonstra padrões fundamentais que podem ser aplicados para criar aplicações muito mais avançadas, como:
|
||||
|
||||
- Assistentes de IA interativos que combinam múltiplos subsistemas especializados.
|
||||
- Pipelines de processamento de dados complexos com transformações aprimoradas por IA.
|
||||
- Agentes autônomos integrados a serviços e APIs externas.
|
||||
- Sistemas de tomada de decisão em múltiplas etapas com processos envolvendo humanos no loop.
|
||||
|
||||
Vamos começar e construir seu primeiro flow!
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
Antes de começar, certifique-se de ter:
|
||||
|
||||
1. Instalado o CrewAI seguindo o [guia de instalação](/pt-BR/installation)
|
||||
2. Configurado sua chave de API LLM no ambiente, conforme o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm)
|
||||
3. Conhecimentos básicos de Python
|
||||
|
||||
## Passo 1: Crie um Novo Projeto de CrewAI Flow
|
||||
|
||||
Primeiro, vamos criar um novo projeto de Flow do CrewAI usando a CLI. Este comando configura um projeto com todos os diretórios necessários e arquivos de template para seu flow.
|
||||
|
||||
```bash
|
||||
crewai create flow guide_creator_flow
|
||||
cd guide_creator_flow
|
||||
```
|
||||
|
||||
Isso gerará um projeto com a estrutura básica necessária para seu flow.
|
||||
|
||||
<Frame caption="Visão Geral do Framework CrewAI">
|
||||
<img src="/images/flows.png" alt="CrewAI Framework Overview" />
|
||||
</Frame>
|
||||
|
||||
## Passo 2: Entendendo a Estrutura do Projeto
|
||||
|
||||
O projeto gerado possui a seguinte estrutura. Reserve um momento para conhecê-la, pois isso ajudará você a criar flows mais complexos no futuro.
|
||||
|
||||
```
|
||||
guide_creator_flow/
|
||||
├── .gitignore
|
||||
├── pyproject.toml
|
||||
├── README.md
|
||||
├── .env
|
||||
├── main.py
|
||||
├── crews/
|
||||
│ └── poem_crew/
|
||||
│ ├── config/
|
||||
│ │ ├── agents.yaml
|
||||
│ │ └── tasks.yaml
|
||||
│ └── poem_crew.py
|
||||
└── tools/
|
||||
└── custom_tool.py
|
||||
```
|
||||
|
||||
Esta estrutura oferece uma separação clara entre os diferentes componentes do seu flow:
|
||||
- A lógica principal do flow no arquivo `main.py`
|
||||
- Crews especializados no diretório `crews`
|
||||
- Ferramentas customizadas no diretório `tools`
|
||||
|
||||
Vamos modificar esta estrutura para criar nosso flow de criação de guias, que irá orquestrar o processo de geração de guias de aprendizagem abrangentes.
|
||||
|
||||
## Passo 3: Adicione um Crew de Redator de Conteúdo
|
||||
|
||||
Nosso flow precisará de um crew especializado para lidar com o processo de criação de conteúdo. Vamos usar a CLI do CrewAI para adicionar um crew de redatores de conteúdo:
|
||||
|
||||
```bash
|
||||
crewai flow add-crew content-crew
|
||||
```
|
||||
|
||||
Este comando cria automaticamente os diretórios e arquivos de template necessários para seu crew. O crew de redatores será responsável por escrever e revisar seções do nosso guia, trabalhando dentro do flow orquestrado pela aplicação principal.
|
||||
|
||||
## Passo 4: Configure o Crew de Redator de Conteúdo
|
||||
|
||||
Agora, vamos modificar os arquivos gerados para o crew de redatores. Vamos configurar dois agentes especializados – um escritor e um revisor – que irão colaborar para criar um conteúdo de alta qualidade para o nosso guia.
|
||||
|
||||
1. Primeiro, atualize o arquivo de configuração de agents para definir a equipe de criação de conteúdo:
|
||||
|
||||
Lembre-se de configurar o `llm` com o provedor que está utilizando.
|
||||
|
||||
```yaml
|
||||
# src/guide_creator_flow/crews/content_crew/config/agents.yaml
|
||||
content_writer:
|
||||
role: >
|
||||
Redator de Conteúdo Educacional
|
||||
goal: >
|
||||
Criar conteúdo envolvente e informativo que explique completamente o tema proposto
|
||||
e forneça insights valiosos ao leitor
|
||||
backstory: >
|
||||
Você é um talentoso escritor educacional com experiência em criar conteúdo claro
|
||||
e atraente. Você tem facilidade para explicar conceitos complexos em linguagem acessível
|
||||
e organizar as informações de forma a ajudar o leitor a construir seu entendimento.
|
||||
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
|
||||
|
||||
content_reviewer:
|
||||
role: >
|
||||
Revisor(a) e Editor(a) de Conteúdo Educacional
|
||||
goal: >
|
||||
Garantir que o conteúdo seja preciso, abrangente, bem estruturado e mantenha
|
||||
consistência com as seções previamente escritas
|
||||
backstory: >
|
||||
Você é um editor(a) meticuloso(a) com anos de experiência revisando conteúdo educacional.
|
||||
Tem atenção aos detalhes, clareza e coesão. Você se destaca em aprimorar conteúdo
|
||||
mantendo o estilo do autor original e garantindo qualidade consistente em várias seções.
|
||||
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
|
||||
```
|
||||
|
||||
Essas definições de agents estabelecem papéis e perspectivas especializadas que irão moldar como nossos agentes de IA abordam a criação de conteúdo. Note como cada agent possui um propósito e expertise distintos.
|
||||
|
||||
2. Em seguida, atualize o arquivo de configuração de tarefas para definir as tarefas específicas de escrita e revisão:
|
||||
|
||||
```yaml
|
||||
# src/guide_creator_flow/crews/content_crew/config/tasks.yaml
|
||||
write_section_task:
|
||||
description: >
|
||||
Escreva uma seção abrangente sobre o tema: "{section_title}"
|
||||
|
||||
Descrição da seção: {section_description}
|
||||
Público-alvo: {audience_level} aprendizes
|
||||
|
||||
Seu conteúdo deve:
|
||||
1. Começar com uma breve introdução ao tema da seção
|
||||
2. Explicar claramente todos os conceitos principais com exemplos
|
||||
3. Incluir aplicações práticas ou exercícios onde apropriado
|
||||
4. Terminar com um resumo dos pontos principais
|
||||
5. Ter aproximadamente 500-800 palavras
|
||||
|
||||
Formate seu conteúdo em Markdown com títulos, listas e ênfase apropriados.
|
||||
|
||||
Seções previamente escritas:
|
||||
{previous_sections}
|
||||
|
||||
Certifique-se de que seu conteúdo mantenha consistência com as seções já escritas
|
||||
e amplie os conceitos que já foram explicados.
|
||||
expected_output: >
|
||||
Uma seção bem estruturada e abrangente em formato Markdown que explique
|
||||
totalmente o tema e é apropriada para o público-alvo.
|
||||
agent: content_writer
|
||||
|
||||
review_section_task:
|
||||
description: >
|
||||
Revise e melhore a seguinte seção sobre "{section_title}":
|
||||
|
||||
{draft_content}
|
||||
|
||||
Público-alvo: {audience_level} aprendizes
|
||||
|
||||
Seções previamente escritas:
|
||||
{previous_sections}
|
||||
|
||||
Sua revisão deve:
|
||||
1. Corrigir qualquer erro gramatical ou de ortografia
|
||||
2. Melhorar clareza e legibilidade
|
||||
3. Garantir que o conteúdo seja abrangente e preciso
|
||||
4. Verificar a consistência com as seções já escritas
|
||||
5. Aprimorar a estrutura e o fluxo
|
||||
6. Adicionar qualquer informação-chave ausente
|
||||
|
||||
Forneça a versão aprimorada da seção em formato Markdown.
|
||||
expected_output: >
|
||||
Uma versão melhorada e refinada da seção, mantendo a estrutura original,
|
||||
mas aprimorando clareza, precisão e consistência.
|
||||
agent: content_reviewer
|
||||
context:
|
||||
- write_section_task
|
||||
```
|
||||
|
||||
Essas definições de tarefas fornecem instruções detalhadas para nossos agents, garantindo que eles produzam conteúdo que atenda aos padrões de qualidade. Observe como o parâmetro `context` na tarefa de revisão cria um fluxo onde o revisor tem acesso à produção do redator.
|
||||
|
||||
3. Agora, atualize o arquivo de implementação do crew para definir como nossos agents e tasks trabalham juntos:
|
||||
|
||||
```python
|
||||
# src/guide_creator_flow/crews/content_crew/content_crew.py
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from crewai.project import CrewBase, agent, crew, task
|
||||
from crewai.agents.agent_builder.base_agent import BaseAgent
|
||||
from typing import List
|
||||
|
||||
@CrewBase
|
||||
class ContentCrew():
|
||||
"""Crew de redação de conteúdo"""
|
||||
|
||||
agents: List[BaseAgent]
|
||||
tasks: List[Task]
|
||||
|
||||
@agent
|
||||
def content_writer(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['content_writer'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
@agent
|
||||
def content_reviewer(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['content_reviewer'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
@task
|
||||
def write_section_task(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['write_section_task'] # type: ignore[index]
|
||||
)
|
||||
|
||||
@task
|
||||
def review_section_task(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['review_section_task'], # type: ignore[index]
|
||||
context=[self.write_section_task()]
|
||||
)
|
||||
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
"""Cria o crew de redação de conteúdo"""
|
||||
return Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
verbose=True,
|
||||
)
|
||||
```
|
||||
|
||||
Essa definição de crew estabelece o relacionamento entre nossos agents e tasks, definindo um processo sequencial onde o redator cria o rascunho e o revisor o aprimora. Embora este crew possa funcionar de forma independente, em nosso flow ele será orquestrado como parte de um sistema maior.
|
||||
|
||||
## Passo 5: Crie o Flow
|
||||
|
||||
Agora vem a parte emocionante – criar o flow que irá orquestrar todo o processo de criação do guia. Aqui iremos combinar código Python regular, chamadas diretas a LLM e nosso crew de criação de conteúdo em um sistema coeso.
|
||||
|
||||
Nosso flow irá:
|
||||
1. Obter a entrada do usuário sobre o tema e nível do público
|
||||
2. Fazer uma chamada direta à LLM para criar um roteiro estruturado do guia
|
||||
3. Processar cada seção sequencialmente usando o crew de redatores
|
||||
4. Combinar tudo em um documento final abrangente
|
||||
|
||||
Vamos criar nosso flow no arquivo `main.py`:
|
||||
|
||||
```python
|
||||
# [CÓDIGO NÃO TRADUZIDO, MANTER COMO ESTÁ]
|
||||
```
|
||||
|
||||
Vamos analisar o que está acontecendo neste flow:
|
||||
|
||||
1. Definimos modelos Pydantic para dados estruturados, garantindo segurança de tipos e representação clara dos dados.
|
||||
2. Criamos uma classe de estado para manter dados entre os diferentes passos do flow.
|
||||
3. Implementamos três etapas principais para o flow:
|
||||
- Obtenção da entrada do usuário com o decorator `@start()`
|
||||
- Criação do roteiro do guia com uma chamada direta à LLM
|
||||
- Processamento das seções com nosso crew de conteúdo
|
||||
4. Usamos o decorator `@listen()` para estabelecer relações orientadas a eventos entre as etapas
|
||||
|
||||
Este é o poder dos flows – combinar diferentes tipos de processamento (interação com usuário, chamadas diretas a IA, tarefas colaborativas com crews) em um sistema orientado a eventos e coeso.
|
||||
|
||||
## Passo 6: Configure suas Variáveis de Ambiente
|
||||
|
||||
Crie um arquivo `.env` na raiz do projeto com suas chaves de API. Veja o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm) para detalhes sobre como configurar o provedor.
|
||||
|
||||
```sh .env
|
||||
OPENAI_API_KEY=sua_chave_openai
|
||||
# ou
|
||||
GEMINI_API_KEY=sua_chave_gemini
|
||||
# ou
|
||||
ANTHROPIC_API_KEY=sua_chave_anthropic
|
||||
```
|
||||
|
||||
## Passo 7: Instale as Dependências
|
||||
|
||||
Instale as dependências necessárias:
|
||||
|
||||
```bash
|
||||
crewai install
|
||||
```
|
||||
|
||||
## Passo 8: Execute Seu Flow
|
||||
|
||||
Agora é hora de ver seu flow em ação! Execute-o usando a CLI do CrewAI:
|
||||
|
||||
```bash
|
||||
crewai flow kickoff
|
||||
```
|
||||
|
||||
Quando você rodar esse comando, verá seu flow ganhando vida:
|
||||
1. Ele solicitará um tema e o nível do público para você
|
||||
2. Criará um roteiro estruturado para o seu guia
|
||||
3. Processará cada seção, com o redator e o revisor colaborando em cada uma
|
||||
4. Por fim, irá compilar tudo em um guia abrangente
|
||||
|
||||
Isso demonstra o poder dos flows para orquestrar processos complexos envolvendo múltiplos componentes, tanto de IA quanto não-IA.
|
||||
|
||||
## Passo 9: Visualize Seu Flow
|
||||
|
||||
Uma das funcionalidades mais poderosas dos flows é a possibilidade de visualizar sua estrutura:
|
||||
|
||||
```bash
|
||||
crewai flow plot
|
||||
```
|
||||
|
||||
Isso irá criar um arquivo HTML que mostra a estrutura do seu flow, incluindo os relacionamentos entre etapas e o fluxo de dados. Essa visualização pode ser inestimável para entender e depurar flows complexos.
|
||||
|
||||
## Passo 10: Revise o Resultado
|
||||
|
||||
Depois que o flow finalizar, você encontrará dois arquivos no diretório `output`:
|
||||
|
||||
1. `guide_outline.json`: Contém o roteiro estruturado do guia
|
||||
2. `complete_guide.md`: O guia abrangente com todas as seções
|
||||
|
||||
Reserve um momento para revisar esses arquivos e apreciar o que você construiu – um sistema que combina entrada do usuário, interações diretas com IA e trabalho colaborativo de agents para produzir um output complexo e de alta qualidade.
|
||||
|
||||
## A Arte do Possível: Além do Seu Primeiro Flow
|
||||
|
||||
O que você aprendeu neste guia é uma base para criar sistemas de IA muito mais sofisticados. Veja algumas formas de expandir este flow básico:
|
||||
|
||||
### Aprimorando a Interação com o Usuário
|
||||
|
||||
Você pode criar flows mais interativos com:
|
||||
- Interfaces web para entrada e saída de dados
|
||||
- Atualizações em tempo real de progresso
|
||||
- Loops de feedback e refinamento interativos
|
||||
- Interações multi-stage com o usuário
|
||||
|
||||
### Adicionando Mais Etapas de Processamento
|
||||
|
||||
Você pode expandir seu flow com etapas adicionais para:
|
||||
- Pesquisa antes da criação do roteiro
|
||||
- Geração de imagens para ilustrações
|
||||
- Geração de snippets de código para guias técnicos
|
||||
- Garantia de qualidade e checagem final de fatos
|
||||
|
||||
### Criando Flows Mais Complexos
|
||||
|
||||
Você pode implementar padrões de flow mais sofisticados:
|
||||
- Ramificações condicionais com base na preferência do usuário ou tipo de conteúdo
|
||||
- Processamento paralelo de seções independentes
|
||||
- Loops de refinamento iterativo com feedback
|
||||
- Integração a APIs e serviços externos
|
||||
|
||||
### Aplicando a Diferentes Domínios
|
||||
|
||||
Os mesmos padrões podem ser usados para criar flows de:
|
||||
- **Narrativas interativas**: criação de histórias personalizadas com base na entrada do usuário
|
||||
- **Inteligência de negócios**: processamento de dados, geração de insights e criação de relatórios
|
||||
- **Desenvolvimento de produtos**: facilitação de ideação, design e planejamento
|
||||
- **Sistemas educacionais**: criação de experiências de aprendizagem personalizadas
|
||||
|
||||
## Principais Funcionalidades Demonstradas
|
||||
|
||||
Este flow de criação de guia demonstra diversos recursos poderosos do CrewAI:
|
||||
|
||||
1. **Interação com o usuário**: O flow coleta input diretamente do usuário
|
||||
2. **Chamadas diretas à LLM**: Usa a classe LLM para interações eficientes e direcionadas com IA
|
||||
3. **Dados estruturados com Pydantic**: Usa Pydantic para garantir segurança de tipos
|
||||
4. **Processamento sequencial com contexto**: Escreve seções em ordem, fornecendo as anteriores como contexto
|
||||
5. **Crews multiagentes**: Utiliza agents especializados (redator e revisor) para criação de conteúdo
|
||||
6. **Gerenciamento de estado**: Mantém estado entre diferentes etapas do processo
|
||||
7. **Arquitetura orientada a eventos**: Usa o decorator `@listen` para responder a eventos
|
||||
|
||||
## Entendendo a Estrutura do Flow
|
||||
|
||||
Vamos decompor os principais componentes dos flows para ajudá-lo a entender como construir o seu:
|
||||
|
||||
### 1. Chamadas Diretas à LLM
|
||||
|
||||
Flows permitem que você faça chamadas diretas a modelos de linguagem quando precisa de respostas simples e estruturadas:
|
||||
|
||||
```python
|
||||
llm = LLM(
|
||||
model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude...
|
||||
response_format=GuideOutline
|
||||
)
|
||||
response = llm.call(messages=messages)
|
||||
```
|
||||
|
||||
Isso é mais eficiente do que usar um crew quando você precisa de um output específico e estruturado.
|
||||
|
||||
### 2. Arquitetura Orientada a Eventos
|
||||
|
||||
Flows usam decorators para estabelecer relações entre componentes:
|
||||
|
||||
```python
|
||||
@start()
|
||||
def get_user_input(self):
|
||||
# Primeira etapa no flow
|
||||
# ...
|
||||
|
||||
@listen(get_user_input)
|
||||
def create_guide_outline(self, state):
|
||||
# Esta roda quando get_user_input é concluída
|
||||
# ...
|
||||
```
|
||||
|
||||
Isso cria uma estrutura clara e declarativa para sua aplicação.
|
||||
|
||||
### 3. Gerenciamento de Estado
|
||||
|
||||
Flows mantêm o estado entre as etapas, facilitando o compartilhamento de dados:
|
||||
|
||||
```python
|
||||
class GuideCreatorState(BaseModel):
|
||||
topic: str = ""
|
||||
audience_level: str = ""
|
||||
guide_outline: GuideOutline = None
|
||||
sections_content: Dict[str, str] = {}
|
||||
```
|
||||
|
||||
Isso fornece uma maneira segura e tipada de rastrear e transformar dados ao longo do flow.
|
||||
|
||||
### 4. Integração com Crews
|
||||
|
||||
Flows podem integrar crews para tarefas colaborativas complexas:
|
||||
|
||||
```python
|
||||
result = ContentCrew().crew().kickoff(inputs={
|
||||
"section_title": section.title,
|
||||
# ...
|
||||
})
|
||||
```
|
||||
|
||||
Assim, você usa a ferramenta certa para cada parte da aplicação – chamadas diretas para tarefas simples e crews para colaboração avançada.
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
Agora que você construiu seu primeiro flow, pode:
|
||||
|
||||
1. Experimentar estruturas e padrões mais complexos de flow
|
||||
2. Testar o uso do `@router()` para criar ramificações condicionais em seus flows
|
||||
3. Explorar as funções `and_` e `or_` para execuções paralelas e mais complexas
|
||||
4. Conectar seu flow a APIs externas, bancos de dados ou interfaces de usuário
|
||||
5. Combinar múltiplos crews especializados em um único flow
|
||||
|
||||
<Check>
|
||||
Parabéns! Você construiu seu primeiro CrewAI Flow que combina código regular, chamadas diretas a LLM e processamento baseado em crews para criar um guia abrangente. Essas habilidades fundamentais permitem criar aplicações de IA cada vez mais sofisticadas, capazes de resolver problemas complexos de múltiplas etapas por meio de controle procedural e inteligência colaborativa.
|
||||
</Check>
|
||||
294
docs/pt-BR/guides/flows/mastering-flow-state.mdx
Normal file
294
docs/pt-BR/guides/flows/mastering-flow-state.mdx
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user