mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-01-10 00:28:31 +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
593
docs/pt-BR/concepts/agents.mdx
Normal file
593
docs/pt-BR/concepts/agents.mdx
Normal file
@@ -0,0 +1,593 @@
|
||||
---
|
||||
title: Agentes
|
||||
description: Guia detalhado sobre como criar e gerenciar agentes no framework CrewAI.
|
||||
icon: robot
|
||||
---
|
||||
|
||||
## Visão Geral de um Agente
|
||||
|
||||
No framework CrewAI, um `Agent` é uma unidade autônoma que pode:
|
||||
- Executar tarefas específicas
|
||||
- Tomar decisões com base em seu papel e objetivo
|
||||
- Utilizar ferramentas para alcançar objetivos
|
||||
- Comunicar e colaborar com outros agentes
|
||||
- Manter a memória de interações
|
||||
- Delegar tarefas, quando permitido
|
||||
|
||||
<Tip>
|
||||
Pense em um agente como um membro especializado da equipe com habilidades, competências e responsabilidades específicas. Por exemplo, um agente `Researcher` pode ser excelente em coletar e analisar informações, enquanto um agente `Writer` pode ser melhor na criação de conteúdo.
|
||||
</Tip>
|
||||
|
||||
<Note type="info" title="Aprimoramento Empresarial: Construtor Visual de Agentes">
|
||||
O CrewAI Enterprise inclui um Construtor Visual de Agentes, que simplifica a criação e configuração de agentes sem escrever código. Projete seus agentes visualmente e teste-os em tempo real.
|
||||
|
||||
|
||||
|
||||
O Construtor Visual de Agentes permite:
|
||||
- Configuração intuitiva de agentes com interfaces baseadas em formulários
|
||||
- Testes e validação em tempo real
|
||||
- Biblioteca de modelos com tipos de agentes pré-configurados
|
||||
- Fácil personalização de atributos e comportamentos do agente
|
||||
</Note>
|
||||
|
||||
## Atributos do Agente
|
||||
|
||||
| Atributo | Parâmetro | Tipo | Descrição |
|
||||
| :-------------------------------------- | :----------------------- | :---------------------------- | :----------------------------------------------------------------------------------------------------------------- |
|
||||
| **Role (Função)** | `role` | `str` | Define a função e a área de especialização do agente dentro da equipe. |
|
||||
| **Goal (Objetivo)** | `goal` | `str` | O objetivo individual que guia a tomada de decisão do agente. |
|
||||
| **Backstory (História de fundo)** | `backstory` | `str` | Fornece contexto e personalidade ao agente, enriquecendo as interações. |
|
||||
| **LLM** _(opcional)_ | `llm` | `Union[str, LLM, Any]` | Modelo de linguagem que alimenta o agente. Padrão: modelo especificado em `OPENAI_MODEL_NAME` ou "gpt-4". |
|
||||
| **Tools (Ferramentas)** _(opcional)_ | `tools` | `List[BaseTool]` | Capacidades ou funções disponíveis para o agente. Padrão: lista vazia. |
|
||||
| **Function Calling LLM** _(opcional)_ | `function_calling_llm` | `Optional[Any]` | Modelo de linguagem usado para chamada de ferramentas, sobrescreve LLM principal se especificado. |
|
||||
| **Max Iterations** _(opcional)_ | `max_iter` | `int` | Número máximo de iterações antes do agente fornecer sua melhor resposta. Padrão: 20. |
|
||||
| **Max RPM** _(opcional)_ | `max_rpm` | `Optional[int]` | Quantidade máxima de requisições por minuto para evitar limites de taxa. |
|
||||
| **Max Execution Time** _(opcional)_ | `max_execution_time` | `Optional[int]` | Tempo máximo (em segundos) de execução da tarefa. |
|
||||
| **Verbose** _(opcional)_ | `verbose` | `bool` | Habilita logs detalhados de execução para depuração. Padrão: False. |
|
||||
| **Allow Delegation** _(opcional)_ | `allow_delegation` | `bool` | Permite que o agente delegue tarefas para outros agentes. Padrão: False. |
|
||||
| **Step Callback** _(opcional)_ | `step_callback` | `Optional[Any]` | Função chamada após cada passo do agente, sobrescreve callback da equipe. |
|
||||
| **Cache** _(opcional)_ | `cache` | `bool` | Ativa cache para o uso de ferramentas. Padrão: True. |
|
||||
| **System Template** _(opcional)_ | `system_template` | `Optional[str]` | Template personalizado de prompt de sistema para o agente. |
|
||||
| **Prompt Template** _(opcional)_ | `prompt_template` | `Optional[str]` | Template de prompt personalizado para o agente. |
|
||||
| **Response Template** _(opcional)_ | `response_template` | `Optional[str]` | Template de resposta personalizado para o agente. |
|
||||
| **Allow Code Execution** _(opcional)_ | `allow_code_execution` | `Optional[bool]` | Ativa execução de código pelo agente. Padrão: False. |
|
||||
| **Max Retry Limit** _(opcional)_ | `max_retry_limit` | `int` | Número máximo de tentativas (retries) em caso de erro. Padrão: 2. |
|
||||
| **Respect Context Window** _(opcional)_ | `respect_context_window` | `bool` | Mantém as mensagens dentro do tamanho da janela de contexto, resumindo quando necessário. Padrão: True. |
|
||||
| **Code Execution Mode** _(opcional)_ | `code_execution_mode` | `Literal["safe", "unsafe"]` | Modo de execução de código: 'safe' (usando Docker) ou 'unsafe' (direto). Padrão: 'safe'. |
|
||||
| **Multimodal** _(opcional)_ | `multimodal` | `bool` | Se o agente suporta capacidades multimodais. Padrão: False. |
|
||||
| **Inject Date** _(opcional)_ | `inject_date` | `bool` | Se deve injetar automaticamente a data atual nas tarefas. Padrão: False. |
|
||||
| **Date Format** _(opcional)_ | `date_format` | `str` | Formato de data utilizado quando `inject_date` está ativo. Padrão: "%Y-%m-%d" (formato ISO). |
|
||||
| **Reasoning** _(opcional)_ | `reasoning` | `bool` | Se o agente deve refletir e criar um plano antes de executar uma tarefa. Padrão: False. |
|
||||
| **Max Reasoning Attempts** _(opcional)_ | `max_reasoning_attempts` | `Optional[int]` | Número máximo de tentativas de raciocínio antes de executar a tarefa. Se None, tentará até estar pronto. |
|
||||
| **Embedder** _(opcional)_ | `embedder` | `Optional[Dict[str, Any]]` | Configuração do embedder utilizado pelo agente. |
|
||||
| **Knowledge Sources** _(opcional)_ | `knowledge_sources` | `Optional[List[BaseKnowledgeSource]]` | Fontes de conhecimento disponíveis para o agente. |
|
||||
| **Use System Prompt** _(opcional)_ | `use_system_prompt` | `Optional[bool]` | Se deve usar o system prompt (suporte para modelo o1). Padrão: True. |
|
||||
|
||||
## Criando Agentes
|
||||
|
||||
Existem duas maneiras de criar agentes no CrewAI: usando **configuração YAML (recomendado)** ou definindo-os **diretamente em código**.
|
||||
|
||||
### Configuração em YAML (Recomendado)
|
||||
|
||||
Usar configuração em YAML proporciona uma maneira mais limpa e fácil de manter para definir agentes. Recomendamos fortemente esse método em seus projetos CrewAI.
|
||||
|
||||
Depois de criar seu projeto CrewAI conforme descrito na seção de [Instalação](/pt-BR/installation), navegue até o arquivo `src/latest_ai_development/config/agents.yaml` e edite o template para atender aos seus requisitos.
|
||||
|
||||
<Note>
|
||||
Variáveis em seus arquivos YAML (como `{topic}`) serão substituídas pelos valores fornecidos em seus inputs ao executar o crew:
|
||||
```python Code
|
||||
crew.kickoff(inputs={'topic': 'AI Agents'})
|
||||
```
|
||||
</Note>
|
||||
|
||||
Veja um exemplo de como configurar agentes usando YAML:
|
||||
|
||||
```yaml agents.yaml
|
||||
# src/latest_ai_development/config/agents.yaml
|
||||
researcher:
|
||||
role: >
|
||||
{topic} Senior Data Researcher
|
||||
goal: >
|
||||
Uncover cutting-edge developments in {topic}
|
||||
backstory: >
|
||||
You're a seasoned researcher with a knack for uncovering the latest
|
||||
developments in {topic}. Known for your ability to find the most relevant
|
||||
information and present it in a clear and concise manner.
|
||||
|
||||
reporting_analyst:
|
||||
role: >
|
||||
{topic} Reporting Analyst
|
||||
goal: >
|
||||
Create detailed reports based on {topic} data analysis and research findings
|
||||
backstory: >
|
||||
You're a meticulous analyst with a keen eye for detail. You're known for
|
||||
your ability to turn complex data into clear and concise reports, making
|
||||
it easy for others to understand and act on the information you provide.
|
||||
```
|
||||
|
||||
Para usar essa configuração YAML no seu código, crie uma classe de crew que herda de `CrewBase`:
|
||||
|
||||
```python Code
|
||||
# src/latest_ai_development/crew.py
|
||||
from crewai import Agent, Crew, Process
|
||||
from crewai.project import CrewBase, agent, crew
|
||||
from crewai_tools import SerperDevTool
|
||||
|
||||
@CrewBase
|
||||
class LatestAiDevelopmentCrew():
|
||||
"""LatestAiDevelopment crew"""
|
||||
|
||||
agents_config = "config/agents.yaml"
|
||||
|
||||
@agent
|
||||
def researcher(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['researcher'], # type: ignore[index]
|
||||
verbose=True,
|
||||
tools=[SerperDevTool()]
|
||||
)
|
||||
|
||||
@agent
|
||||
def reporting_analyst(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['reporting_analyst'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
<Note>
|
||||
Os nomes utilizados em seus arquivos YAML (`agents.yaml`) devem ser iguais aos nomes dos métodos no seu código Python.
|
||||
</Note>
|
||||
|
||||
### Definição Direta em Código
|
||||
|
||||
Você pode criar agentes diretamente em código instanciando a classe `Agent`. Veja um exemplo abrangente mostrando todos os parâmetros disponíveis:
|
||||
|
||||
```python Code
|
||||
from crewai import Agent
|
||||
from crewai_tools import SerperDevTool
|
||||
|
||||
# Crie um agente com todos os parâmetros disponíveis
|
||||
agent = Agent(
|
||||
role="Senior Data Scientist",
|
||||
goal="Analyze and interpret complex datasets to provide actionable insights",
|
||||
backstory="With over 10 years of experience in data science and machine learning, "
|
||||
"you excel at finding patterns in complex datasets.",
|
||||
llm="gpt-4", # Default: OPENAI_MODEL_NAME or "gpt-4"
|
||||
function_calling_llm=None, # Optional: Separate LLM for tool calling
|
||||
verbose=False, # Default: False
|
||||
allow_delegation=False, # Default: False
|
||||
max_iter=20, # Default: 20 iterations
|
||||
max_rpm=None, # Optional: Rate limit for API calls
|
||||
max_execution_time=None, # Optional: Maximum execution time in seconds
|
||||
max_retry_limit=2, # Default: 2 retries on error
|
||||
allow_code_execution=False, # Default: False
|
||||
code_execution_mode="safe", # Default: "safe" (options: "safe", "unsafe")
|
||||
respect_context_window=True, # Default: True
|
||||
use_system_prompt=True, # Default: True
|
||||
multimodal=False, # Default: False
|
||||
inject_date=False, # Default: False
|
||||
date_format="%Y-%m-%d", # Default: ISO format
|
||||
reasoning=False, # Default: False
|
||||
max_reasoning_attempts=None, # Default: None
|
||||
tools=[SerperDevTool()], # Optional: List of tools
|
||||
knowledge_sources=None, # Optional: List of knowledge sources
|
||||
embedder=None, # Optional: Custom embedder configuration
|
||||
system_template=None, # Optional: Custom system prompt template
|
||||
prompt_template=None, # Optional: Custom prompt template
|
||||
response_template=None, # Optional: Custom response template
|
||||
step_callback=None, # Optional: Callback function for monitoring
|
||||
)
|
||||
```
|
||||
|
||||
Vamos detalhar algumas combinações de parâmetros-chave para casos de uso comuns:
|
||||
|
||||
#### Agente de Pesquisa Básico
|
||||
```python Code
|
||||
research_agent = Agent(
|
||||
role="Research Analyst",
|
||||
goal="Find and summarize information about specific topics",
|
||||
backstory="You are an experienced researcher with attention to detail",
|
||||
tools=[SerperDevTool()],
|
||||
verbose=True # Enable logging for debugging
|
||||
)
|
||||
```
|
||||
|
||||
#### Agente de Desenvolvimento de Código
|
||||
```python Code
|
||||
dev_agent = Agent(
|
||||
role="Senior Python Developer",
|
||||
goal="Write and debug Python code",
|
||||
backstory="Expert Python developer with 10 years of experience",
|
||||
allow_code_execution=True,
|
||||
code_execution_mode="safe", # Uses Docker for safety
|
||||
max_execution_time=300, # 5-minute timeout
|
||||
max_retry_limit=3 # More retries for complex code tasks
|
||||
)
|
||||
```
|
||||
|
||||
#### Agente de Análise de Longa Duração
|
||||
```python Code
|
||||
analysis_agent = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Perform deep analysis of large datasets",
|
||||
backstory="Specialized in big data analysis and pattern recognition",
|
||||
memory=True,
|
||||
respect_context_window=True,
|
||||
max_rpm=10, # Limit API calls
|
||||
function_calling_llm="gpt-4o-mini" # Cheaper model for tool calls
|
||||
)
|
||||
```
|
||||
|
||||
#### Agente com Template Personalizado
|
||||
```python Code
|
||||
custom_agent = Agent(
|
||||
role="Customer Service Representative",
|
||||
goal="Assist customers with their inquiries",
|
||||
backstory="Experienced in customer support with a focus on satisfaction",
|
||||
system_template="""<|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|>""",
|
||||
)
|
||||
```
|
||||
|
||||
#### Agente Ciente de Data, com Raciocínio
|
||||
```python Code
|
||||
strategic_agent = Agent(
|
||||
role="Market Analyst",
|
||||
goal="Track market movements with precise date references and strategic planning",
|
||||
backstory="Expert in time-sensitive financial analysis and strategic reporting",
|
||||
inject_date=True, # Automatically inject current date into tasks
|
||||
date_format="%B %d, %Y", # Format as "May 21, 2025"
|
||||
reasoning=True, # Enable strategic planning
|
||||
max_reasoning_attempts=2, # Limit planning iterations
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
#### Agente de Raciocínio
|
||||
```python Code
|
||||
reasoning_agent = Agent(
|
||||
role="Strategic Planner",
|
||||
goal="Analyze complex problems and create detailed execution plans",
|
||||
backstory="Expert strategic planner who methodically breaks down complex challenges",
|
||||
reasoning=True, # Enable reasoning and planning
|
||||
max_reasoning_attempts=3, # Limit reasoning attempts
|
||||
max_iter=30, # Allow more iterations for complex planning
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
#### Agente Multimodal
|
||||
```python Code
|
||||
multimodal_agent = Agent(
|
||||
role="Visual Content Analyst",
|
||||
goal="Analyze and process both text and visual content",
|
||||
backstory="Specialized in multimodal analysis combining text and image understanding",
|
||||
multimodal=True, # Enable multimodal capabilities
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
### Detalhes dos Parâmetros
|
||||
|
||||
#### Parâmetros Críticos
|
||||
- `role`, `goal` e `backstory` são obrigatórios e definem o comportamento do agente
|
||||
- `llm` determina o modelo de linguagem utilizado (padrão: GPT-4 da OpenAI)
|
||||
|
||||
#### Memória e Contexto
|
||||
- `memory`: Ative para manter o histórico de conversas
|
||||
- `respect_context_window`: Evita problemas com limites de tokens
|
||||
- `knowledge_sources`: Adicione bases de conhecimento específicas do domínio
|
||||
|
||||
#### Controle de Execução
|
||||
- `max_iter`: Número máximo de tentativas antes da melhor resposta
|
||||
- `max_execution_time`: Tempo limite em segundos
|
||||
- `max_rpm`: Limite de requisições por minuto
|
||||
- `max_retry_limit`: Tentativas de correção em erros
|
||||
|
||||
#### Execução de Código
|
||||
- `allow_code_execution`: Deve ser True para permitir execução de código
|
||||
- `code_execution_mode`:
|
||||
- `"safe"`: Usa Docker (recomendado para produção)
|
||||
- `"unsafe"`: Execução direta (apenas em ambientes confiáveis)
|
||||
|
||||
<Note>
|
||||
Isso executa uma imagem Docker padrão. Se você deseja configurar a imagem Docker, veja a ferramenta Code Interpreter na seção de ferramentas.
|
||||
Adicione a ferramenta de interpretação de código como um parâmetro em ferramentas no agente.
|
||||
</Note>
|
||||
|
||||
#### Funcionalidades Avançadas
|
||||
- `multimodal`: Habilita capacidades multimodais para processar texto e conteúdo visual
|
||||
- `reasoning`: Permite que o agente reflita e crie planos antes de executar tarefas
|
||||
- `inject_date`: Injeta a data atual automaticamente nas descrições das tarefas
|
||||
|
||||
#### Templates
|
||||
- `system_template`: Define o comportamento central do agente
|
||||
- `prompt_template`: Estrutura o formato da entrada
|
||||
- `response_template`: Formata as respostas do agente
|
||||
|
||||
<Note>
|
||||
Ao usar templates personalizados, assegure-se de definir tanto `system_template` quanto `prompt_template`. O `response_template` é opcional, mas recomendado para formatação consistente de saída.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Ao usar templates personalizados, você pode usar variáveis como `{role}`, `{goal}` e `{backstory}` em seus templates. Elas serão automaticamente preenchidas durante a execução.
|
||||
</Note>
|
||||
|
||||
## Ferramentas do Agente
|
||||
|
||||
Agentes podem ser equipados com diversas ferramentas para ampliar suas capacidades. O CrewAI suporta ferramentas do:
|
||||
- [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools)
|
||||
- [LangChain Tools](https://python.langchain.com/docs/integrations/tools)
|
||||
|
||||
Veja como adicionar ferramentas a um agente:
|
||||
|
||||
```python Code
|
||||
from crewai import Agent
|
||||
from crewai_tools import SerperDevTool, WikipediaTools
|
||||
|
||||
# Criar ferramentas
|
||||
search_tool = SerperDevTool()
|
||||
wiki_tool = WikipediaTools()
|
||||
|
||||
# Adicionar ferramentas ao agente
|
||||
researcher = Agent(
|
||||
role="AI Technology Researcher",
|
||||
goal="Research the latest AI developments",
|
||||
tools=[search_tool, wiki_tool],
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
## Memória e Contexto do Agente
|
||||
|
||||
Agentes podem manter a memória de suas interações e usar contexto de tarefas anteriores. Isto é especialmente útil para fluxos de trabalho complexos onde é necessário reter informações ao longo de várias tarefas.
|
||||
|
||||
```python Code
|
||||
from crewai import Agent
|
||||
|
||||
analyst = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze and remember complex data patterns",
|
||||
memory=True, # Enable memory
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
<Note>
|
||||
Quando `memory` está ativo, o agente manterá o contexto ao longo de múltiplas interações, melhorando a capacidade de lidar com tarefas complexas, em múltiplos passos.
|
||||
</Note>
|
||||
|
||||
## Gerenciamento da Janela de Contexto
|
||||
|
||||
O CrewAI inclui um gerenciamento automático sofisticado de janela de contexto para lidar com situações onde as conversas excedem o limite de tokens do modelo de linguagem. Esse poderoso recurso é controlado pelo parâmetro `respect_context_window`.
|
||||
|
||||
### Como Funciona o Gerenciamento de Janela de Contexto
|
||||
|
||||
Quando o histórico de conversas de um agente se torna muito grande para a janela de contexto do LLM, o CrewAI detecta essa situação automaticamente e pode:
|
||||
|
||||
1. **Resumir o conteúdo automaticamente** (com `respect_context_window=True`)
|
||||
2. **Parar a execução com erro** (com `respect_context_window=False`)
|
||||
|
||||
### Manipulação Automática de Contexto (`respect_context_window=True`)
|
||||
|
||||
Esta é a **configuração padrão e recomendada** para a maioria dos casos. Quando ativada, CrewAI irá:
|
||||
|
||||
```python Code
|
||||
# Agente com gerenciamento automático de contexto (padrão)
|
||||
smart_agent = Agent(
|
||||
role="Research Analyst",
|
||||
goal="Analyze large documents and datasets",
|
||||
backstory="Expert at processing extensive information",
|
||||
respect_context_window=True, # 🔑 Default: auto-handle context limits
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
**O que acontece quando os limites de contexto são excedidos:**
|
||||
- ⚠️ **Mensagem de aviso**: `"Context length exceeded. Summarizing content to fit the model context window."`
|
||||
- 🔄 **Resumir automaticamente**: O CrewAI resume o histórico da conversa de forma inteligente
|
||||
- ✅ **Execução contínua**: A execução da tarefa prossegue normalmente com o contexto resumido
|
||||
- 📝 **Informação preservada**: Informações-chave são mantidas enquanto reduz a contagem de tokens
|
||||
|
||||
### Limites Estritos de Contexto (`respect_context_window=False`)
|
||||
|
||||
Quando você precisa de controle total e prefere que a execução pare a perder qualquer informação:
|
||||
|
||||
```python Code
|
||||
# Agente com limites estritos de contexto
|
||||
strict_agent = Agent(
|
||||
role="Legal Document Reviewer",
|
||||
goal="Provide precise legal analysis without information loss",
|
||||
backstory="Legal expert requiring complete context for accurate analysis",
|
||||
respect_context_window=False, # ❌ Stop execution on context limit
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
**O que acontece quando os limites de contexto são excedidos:**
|
||||
- ❌ **Mensagem de erro**: `"Context length exceeded. Consider using smaller text or RAG tools from crewai_tools."`
|
||||
- 🛑 **Execução interrompida**: A execução da tarefa é parada imediatamente
|
||||
- 🔧 **Intervenção manual necessária**: Você precisará modificar sua abordagem
|
||||
|
||||
### Como Escolher a Melhor Configuração
|
||||
|
||||
#### Use `respect_context_window=True` (padrão) quando:
|
||||
- **Processar documentos grandes** que podem ultrapassar os limites de contexto
|
||||
- **Conversas longas** onde certo grau de resumo é aceitável
|
||||
- **Tarefas de pesquisa** onde o contexto geral é mais importante que detalhes exatos
|
||||
- **Prototipagem e desenvolvimento** quando se deseja execução robusta
|
||||
|
||||
```python Code
|
||||
# Ideal para processamento de documentos
|
||||
document_processor = Agent(
|
||||
role="Document Analyst",
|
||||
goal="Extract insights from large research papers",
|
||||
backstory="Expert at analyzing extensive documentation",
|
||||
respect_context_window=True, # Lida com documentos grandes sem problemas
|
||||
max_iter=50, # Permite mais iterações para análises complexas
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
#### Use `respect_context_window=False` quando:
|
||||
- **Precisão é crítica** e perda de informação é inaceitável
|
||||
- **Tarefas jurídicas ou médicas** que requerem contexto completo
|
||||
- **Revisão de código** onde detalhes perdidos podem causar bugs
|
||||
- **Análise financeira** onde precisão é fundamental
|
||||
|
||||
```python Code
|
||||
# Ideal para tarefas de precisão
|
||||
precision_agent = Agent(
|
||||
role="Code Security Auditor",
|
||||
goal="Identify security vulnerabilities in code",
|
||||
backstory="Security expert requiring complete code context",
|
||||
respect_context_window=False, # Prefere falhar do que análise incompleta
|
||||
max_retry_limit=1, # Falha rápida em caso de problemas de contexto
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
### Abordagens Alternativas para Grandes Volumes de Dados
|
||||
|
||||
Ao lidar com conjuntos de dados muito grandes, considere as seguintes estratégias:
|
||||
|
||||
#### 1. Use Ferramentas RAG
|
||||
```python Code
|
||||
from crewai_tools import RagTool
|
||||
|
||||
# Crie uma ferramenta RAG para processamento de documentos grandes
|
||||
rag_tool = RagTool()
|
||||
|
||||
rag_agent = Agent(
|
||||
role="Research Assistant",
|
||||
goal="Query large knowledge bases efficiently",
|
||||
backstory="Expert at using RAG tools for information retrieval",
|
||||
tools=[rag_tool], # Usar RAG ao invés de grandes janelas de contexto
|
||||
respect_context_window=True,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
#### 2. Use Fontes de Conhecimento
|
||||
```python Code
|
||||
# Use fontes de conhecimento ao invés de prompts grandes
|
||||
knowledge_agent = Agent(
|
||||
role="Knowledge Expert",
|
||||
goal="Answer questions using curated knowledge",
|
||||
backstory="Expert at leveraging structured knowledge sources",
|
||||
knowledge_sources=[your_knowledge_sources], # Conhecimento pré-processado
|
||||
respect_context_window=True,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
### Boas Práticas para Janela de Contexto
|
||||
|
||||
1. **Monitore o uso de contexto**: Ative `verbose=True` para visualizar o gerenciamento de contexto em ação
|
||||
2. **Otimize para eficiência**: Estruture tarefas para minimizar o acúmulo de contexto
|
||||
3. **Use modelos apropriados**: Escolha LLMs com janelas de contexto adequadas à sua tarefa
|
||||
4. **Teste ambos os modos**: Experimente `True` e `False` para descobrir o que funciona melhor para seu caso
|
||||
5. **Combine com RAG**: Utilize ferramentas RAG para grandes conjuntos de dados ao invés de depender apenas da janela de contexto
|
||||
|
||||
### Solucionando Problemas de Contexto
|
||||
|
||||
**Se você receber erros de limite de contexto:**
|
||||
```python Code
|
||||
# Solução rápida: Habilite manipulação automática
|
||||
agent.respect_context_window = True
|
||||
|
||||
# Solução melhor: Use ferramentas RAG para dados volumosos
|
||||
from crewai_tools import RagTool
|
||||
agent.tools = [RagTool()]
|
||||
|
||||
# Alternativa: Divida as tarefas em partes menores
|
||||
# Ou use fontes de conhecimento no lugar de prompts extensos
|
||||
```
|
||||
|
||||
**Se o resumo automático perder informações importantes:**
|
||||
```python Code
|
||||
# Desative o resumo automático e use RAG
|
||||
agent = Agent(
|
||||
role="Detailed Analyst",
|
||||
goal="Maintain complete information accuracy",
|
||||
backstory="Expert requiring full context",
|
||||
respect_context_window=False, # Sem resumo automático
|
||||
tools=[RagTool()], # Use RAG para grandes volumes de dados
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
<Note>
|
||||
O recurso de gerenciamento da janela de contexto funciona automaticamente em segundo plano. Você não precisa chamar funções especiais – basta definir `respect_context_window` conforme deseja e o CrewAI cuida do resto!
|
||||
</Note>
|
||||
|
||||
## Considerações e Boas Práticas Importantes
|
||||
|
||||
### Segurança e Execução de Código
|
||||
- Ao usar `allow_code_execution`, seja cauteloso com entradas do usuário e sempre as valide
|
||||
- Use `code_execution_mode: "safe"` (Docker) em ambientes de produção
|
||||
- Considere definir limites adequados de `max_execution_time` para evitar loops infinitos
|
||||
|
||||
### Otimização de Performance
|
||||
- Use `respect_context_window: true` para evitar problemas com limite de tokens
|
||||
- Ajuste `max_rpm` para evitar rate limiting
|
||||
- Ative `cache: true` para melhorar performance em tarefas repetitivas
|
||||
- Ajuste `max_iter` e `max_retry_limit` conforme a complexidade da tarefa
|
||||
|
||||
### Gerenciamento de Memória e Contexto
|
||||
- Considere `knowledge_sources` para informações específicas de domínio
|
||||
- Configure `embedder` ao usar modelos de embedding personalizados
|
||||
- Use templates personalizados (`system_template`, `prompt_template`, `response_template`) para controle fino do comportamento do agente
|
||||
|
||||
### Funcionalidades Avançadas
|
||||
- Ative `reasoning: true` para agentes que precisam planejar e refletir antes de tarefas complexas
|
||||
- Defina `max_reasoning_attempts` para controlar as iterações de planejamento (`None` para ilimitadas)
|
||||
- Use `inject_date: true` para dar consciência temporal a agentes em tarefas que dependem de datas
|
||||
- Personalize o formato de data com `date_format` usando códigos padrões do Python datetime
|
||||
- Ative `multimodal: true` para agentes que precisam processar texto e imagem
|
||||
|
||||
### Colaboração entre Agentes
|
||||
- Ative `allow_delegation: true` quando agentes precisarem trabalhar juntos
|
||||
- Use `step_callback` para monitorar e registrar interações dos agentes
|
||||
- Considere usar LLMs diferentes para propósitos distintos:
|
||||
- `llm` principal para raciocínio complexo
|
||||
- `function_calling_llm` para uso eficiente de ferramentas
|
||||
|
||||
### Consciência de Data e Raciocínio
|
||||
- Use `inject_date: true` para fornecer consciência temporal aos agentes em tarefas sensíveis ao tempo
|
||||
- Customize o formato de data com `date_format` usando códigos standards de datetime do Python
|
||||
- Códigos válidos incluem: %Y (ano), %m (mês), %d (dia), %B (nome completo do mês), etc.
|
||||
- Formatos de data inválidos serão registrados como avisos e não modificarão a descrição da tarefa
|
||||
- Ative `reasoning: true` para tarefas complexas que se beneficiam de planejamento e reflexão antecipados
|
||||
|
||||
### Compatibilidade de Modelos
|
||||
- Defina `use_system_prompt: false` para modelos antigos que não suportam mensagens de sistema
|
||||
- Certifique-se que o `llm` escolhido suporta as funcionalidades necessárias (como function calling)
|
||||
|
||||
## Solução de Problemas Comuns
|
||||
|
||||
1. **Limite de Taxa (Rate Limiting)**: Se atingir limites de API:
|
||||
- Implemente o `max_rpm` adequado
|
||||
- Use cache para operações repetitivas
|
||||
- Considere agrupar requisições em lote
|
||||
|
||||
2. **Erros de Janela de Contexto**: Se exceder limites de contexto:
|
||||
- Habilite `respect_context_window`
|
||||
- Otimize seus prompts
|
||||
- Limpe periodicamente a memória do agente
|
||||
|
||||
3. **Problemas de Execução de Código**: Se a execução de código falhar:
|
||||
- Verifique se o Docker está instalado para o modo seguro
|
||||
- Cheque permissões de execução
|
||||
- Revise as configurações do sandbox de código
|
||||
|
||||
4. **Problemas de Memória**: Se as respostas do agente parecerem inconsistentes:
|
||||
- Cheque a configuração das fontes de conhecimento
|
||||
- Analise o gerenciamento do histórico de conversas
|
||||
|
||||
Lembre-se de que agentes são mais eficientes quando configurados de acordo com o caso de uso específico. Reserve um tempo para entender seus requisitos e ajustar esses parâmetros conforme necessário.
|
||||
312
docs/pt-BR/concepts/cli.mdx
Normal file
312
docs/pt-BR/concepts/cli.mdx
Normal file
@@ -0,0 +1,312 @@
|
||||
---
|
||||
title: CLI
|
||||
description: Aprenda a usar o CLI do CrewAI para interagir com o CrewAI.
|
||||
icon: terminal
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O CLI do CrewAI fornece um conjunto de comandos para interagir com o CrewAI, permitindo que você crie, treine, execute e gerencie crews & flows.
|
||||
|
||||
## Instalação
|
||||
|
||||
Para usar o CLI do CrewAI, certifique-se de que o CrewAI está instalado:
|
||||
|
||||
```shell Terminal
|
||||
pip install crewai
|
||||
```
|
||||
|
||||
## Uso Básico
|
||||
|
||||
A estrutura básica de um comando CLI do CrewAI é:
|
||||
|
||||
```shell Terminal
|
||||
crewai [COMMAND] [OPTIONS] [ARGUMENTS]
|
||||
```
|
||||
|
||||
## Comandos Disponíveis
|
||||
|
||||
### 1. Create
|
||||
|
||||
Crie um novo crew ou flow.
|
||||
|
||||
```shell Terminal
|
||||
crewai create [OPTIONS] TYPE NAME
|
||||
```
|
||||
|
||||
- `TYPE`: Escolha entre "crew" ou "flow"
|
||||
- `NAME`: Nome do crew ou flow
|
||||
|
||||
Exemplo:
|
||||
```shell Terminal
|
||||
crewai create crew my_new_crew
|
||||
crewai create flow my_new_flow
|
||||
```
|
||||
|
||||
### 2. Version
|
||||
|
||||
Mostre a versão instalada do CrewAI.
|
||||
|
||||
```shell Terminal
|
||||
crewai version [OPTIONS]
|
||||
```
|
||||
|
||||
- `--tools`: (Opcional) Mostra a versão instalada das ferramentas do CrewAI
|
||||
|
||||
Exemplo:
|
||||
```shell Terminal
|
||||
crewai version
|
||||
crewai version --tools
|
||||
```
|
||||
|
||||
### 3. Train
|
||||
|
||||
Treine o crew por um número específico de iterações.
|
||||
|
||||
```shell Terminal
|
||||
crewai train [OPTIONS]
|
||||
```
|
||||
|
||||
- `-n, --n_iterations INTEGER`: Número de iterações para treinar o crew (padrão: 5)
|
||||
- `-f, --filename TEXT`: Caminho para um arquivo customizado para treinamento (padrão: "trained_agents_data.pkl")
|
||||
|
||||
Exemplo:
|
||||
```shell Terminal
|
||||
crewai train -n 10 -f my_training_data.pkl
|
||||
```
|
||||
|
||||
### 4. Replay
|
||||
|
||||
Reexecute a execução do crew a partir de uma tarefa específica.
|
||||
|
||||
```shell Terminal
|
||||
crewai replay [OPTIONS]
|
||||
```
|
||||
|
||||
- `-t, --task_id TEXT`: Reexecuta o crew a partir deste task ID, incluindo todas as tarefas subsequentes
|
||||
|
||||
Exemplo:
|
||||
```shell Terminal
|
||||
crewai replay -t task_123456
|
||||
```
|
||||
|
||||
### 5. Log-tasks-outputs
|
||||
|
||||
Recupere as saídas mais recentes das tarefas crew.kickoff() do seu crew.
|
||||
|
||||
```shell Terminal
|
||||
crewai log-tasks-outputs
|
||||
```
|
||||
|
||||
### 6. Reset-memories
|
||||
|
||||
Redefine as memórias do crew (longa, curta, de entidades, latest_crew_kickoff_outputs).
|
||||
|
||||
```shell Terminal
|
||||
crewai reset-memories [OPTIONS]
|
||||
```
|
||||
|
||||
- `-l, --long`: Redefine a memória de LONGO PRAZO
|
||||
- `-s, --short`: Redefine a memória de CURTO PRAZO
|
||||
- `-e, --entities`: Redefine a memória de ENTIDADES
|
||||
- `-k, --kickoff-outputs`: Redefine as OUTPUTS DA TAREFA KICKOFF MAIS RECENTE
|
||||
- `-kn, --knowledge`: Redefine o armazenamento de CONHECIMENTO
|
||||
- `-akn, --agent-knowledge`: Redefine o armazenamento de CONHECIMENTO DOS AGENTES
|
||||
- `-a, --all`: Redefine TODAS as memórias
|
||||
|
||||
Exemplo:
|
||||
```shell Terminal
|
||||
crewai reset-memories --long --short
|
||||
crewai reset-memories --all
|
||||
```
|
||||
|
||||
### 7. Test
|
||||
|
||||
Teste o crew e avalie os resultados.
|
||||
|
||||
```shell Terminal
|
||||
crewai test [OPTIONS]
|
||||
```
|
||||
|
||||
- `-n, --n_iterations INTEGER`: Número de iterações para testar o crew (padrão: 3)
|
||||
- `-m, --model TEXT`: Modelo LLM para executar os testes no Crew (padrão: "gpt-4o-mini")
|
||||
|
||||
Exemplo:
|
||||
```shell Terminal
|
||||
crewai test -n 5 -m gpt-3.5-turbo
|
||||
```
|
||||
|
||||
### 8. Run
|
||||
|
||||
Execute o crew ou flow.
|
||||
|
||||
```shell Terminal
|
||||
crewai run
|
||||
```
|
||||
|
||||
<Note>
|
||||
A partir da versão 0.103.0, o comando `crewai run` pode ser usado para executar tanto crews padrão quanto flows. Para flows, ele detecta automaticamente o tipo a partir do pyproject.toml e executa o comando apropriado. Este é agora o modo recomendado de executar tanto crews quanto flows.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Certifique-se de executar estes comandos a partir do diretório onde seu projeto CrewAI está configurado.
|
||||
Alguns comandos podem exigir configuração ou ajustes adicionais dentro da estrutura do seu projeto.
|
||||
</Note>
|
||||
|
||||
### 9. Chat
|
||||
|
||||
A partir da versão `0.98.0`, ao rodar o comando `crewai chat`, você inicia uma sessão interativa com seu crew. O assistente de IA irá guiá-lo solicitando as entradas necessárias para executar o crew. Uma vez que todas as entradas são fornecidas, o crew executará suas tarefas.
|
||||
|
||||
Depois de receber os resultados, você pode continuar interagindo com o assistente para instruções ou perguntas adicionais.
|
||||
|
||||
```shell Terminal
|
||||
crewai chat
|
||||
```
|
||||
<Note>
|
||||
Garanta que você execute estes comandos a partir do diretório raiz do seu projeto CrewAI.
|
||||
</Note>
|
||||
<Note>
|
||||
IMPORTANTE: Defina a propriedade `chat_llm` no seu arquivo `crew.py` para habilitar este comando.
|
||||
|
||||
```python
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
verbose=True,
|
||||
chat_llm="gpt-4o", # LLM para orquestração de chat
|
||||
)
|
||||
```
|
||||
</Note>
|
||||
|
||||
### 10. Deploy
|
||||
|
||||
Implemente o crew ou flow no [CrewAI Enterprise](https://app.crewai.com).
|
||||
|
||||
- **Autenticação**: Você precisa estar autenticado para implementar no CrewAI Enterprise.
|
||||
```shell Terminal
|
||||
crewai signup
|
||||
```
|
||||
Caso já tenha uma conta, você pode fazer login com:
|
||||
```shell Terminal
|
||||
crewai login
|
||||
```
|
||||
|
||||
- **Criar um deployment**: Depois de autenticado, você pode criar um deployment para seu crew ou flow a partir da raiz do seu projeto local.
|
||||
```shell Terminal
|
||||
crewai deploy create
|
||||
```
|
||||
- Lê a configuração do seu projeto local.
|
||||
- Solicita a confirmação das variáveis de ambiente (como `OPENAI_API_KEY`, `SERPER_API_KEY`) encontradas localmente. Elas serão armazenadas de forma segura junto ao deployment na plataforma Enterprise. Verifique se suas chaves sensíveis estão corretamente configuradas localmente (por exemplo, em um arquivo `.env`) antes de executar este comando.
|
||||
|
||||
### 11. Gerenciamento de Organização
|
||||
|
||||
Gerencie suas organizações no CrewAI Enterprise.
|
||||
|
||||
```shell Terminal
|
||||
crewai org [COMMAND] [OPTIONS]
|
||||
```
|
||||
|
||||
#### Comandos:
|
||||
|
||||
- `list`: Liste todas as organizações das quais você faz parte
|
||||
```shell Terminal
|
||||
crewai org list
|
||||
```
|
||||
|
||||
- `current`: Exibe sua organização ativa atualmente
|
||||
```shell Terminal
|
||||
crewai org current
|
||||
```
|
||||
|
||||
- `switch`: Mude para uma organização específica
|
||||
```shell Terminal
|
||||
crewai org switch <organization_id>
|
||||
```
|
||||
|
||||
<Note>
|
||||
Você deve estar autenticado no CrewAI Enterprise para usar estes comandos de gerenciamento de organização.
|
||||
</Note>
|
||||
|
||||
- **Criar um deployment** (continuação):
|
||||
- Vincula o deployment ao respectivo repositório remoto do GitHub (normalmente detectado automaticamente).
|
||||
|
||||
- **Implantar o Crew**: Depois de autenticado, você pode implantar seu crew ou flow no CrewAI Enterprise.
|
||||
```shell Terminal
|
||||
crewai deploy push
|
||||
```
|
||||
- Inicia o processo de deployment na plataforma CrewAI Enterprise.
|
||||
- Após a iniciação bem-sucedida, será exibida a mensagem Deployment created successfully! juntamente com o Nome do Deployment e um Deployment ID (UUID) único.
|
||||
|
||||
- **Status do Deployment**: Você pode verificar o status do seu deployment com:
|
||||
```shell Terminal
|
||||
crewai deploy status
|
||||
```
|
||||
Isso retorna o status mais recente do último deployment iniciado (por exemplo, `Building Images for Crew`, `Deploy Enqueued`, `Online`).
|
||||
|
||||
- **Logs do Deployment**: Você pode checar os logs do seu deployment com:
|
||||
```shell Terminal
|
||||
crewai deploy logs
|
||||
```
|
||||
Isso faz o streaming dos logs do deployment para seu terminal.
|
||||
|
||||
- **Listar deployments**: Você pode listar todos os seus deployments com:
|
||||
```shell Terminal
|
||||
crewai deploy list
|
||||
```
|
||||
Isto lista todos os seus deployments.
|
||||
|
||||
- **Deletar um deployment**: Você pode deletar um deployment com:
|
||||
```shell Terminal
|
||||
crewai deploy remove
|
||||
```
|
||||
Isto exclui o deployment da plataforma CrewAI Enterprise.
|
||||
|
||||
- **Comando de Ajuda**: Você pode obter ajuda sobre o CLI com:
|
||||
```shell Terminal
|
||||
crewai deploy --help
|
||||
```
|
||||
Isto exibe a mensagem de ajuda para o CLI CrewAI Deploy.
|
||||
|
||||
Assista ao vídeo tutorial para uma demonstração passo-a-passo de implantação do seu crew no [CrewAI Enterprise](http://app.crewai.com) usando o CLI.
|
||||
|
||||
<iframe
|
||||
width="100%"
|
||||
height="400"
|
||||
src="https://www.youtube.com/embed/3EqSV-CYDZA"
|
||||
title="CrewAI Deployment Guide"
|
||||
frameborder="0"
|
||||
style={{ borderRadius: '10px' }}
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
|
||||
### 11. Chaves de API
|
||||
|
||||
Ao executar o comando ```crewai create crew```, o CLI primeiro mostrará os 5 provedores de LLM mais comuns e pedirá para você selecionar um.
|
||||
|
||||
Após selecionar um provedor de LLM, será solicitado que você informe as chaves de API.
|
||||
|
||||
#### Provedores iniciais de chave de API
|
||||
|
||||
Inicialmente, o CLI solicitará as chaves de API para os seguintes serviços:
|
||||
|
||||
* OpenAI
|
||||
* Groq
|
||||
* Anthropic
|
||||
* Google Gemini
|
||||
* SambaNova
|
||||
|
||||
Ao selecionar um provedor, o CLI solicitará que você insira sua chave de API.
|
||||
|
||||
#### Outras opções
|
||||
|
||||
Se você selecionar a opção 6, será possível escolher de uma lista de provedores suportados pelo LiteLLM.
|
||||
|
||||
Ao escolher um provedor, o CLI solicitará que você informe o nome da chave e a chave de API.
|
||||
|
||||
Veja o seguinte link para o nome de chave de cada provedor:
|
||||
|
||||
* [LiteLLM Providers](https://docs.litellm.ai/docs/providers)
|
||||
362
docs/pt-BR/concepts/collaboration.mdx
Normal file
362
docs/pt-BR/concepts/collaboration.mdx
Normal file
@@ -0,0 +1,362 @@
|
||||
---
|
||||
title: Colaboração
|
||||
description: Como permitir que agentes trabalhem juntos, deleguem tarefas e se comuniquem de forma eficaz em equipes CrewAI.
|
||||
icon: screen-users
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
A colaboração no CrewAI permite que agentes trabalhem juntos como uma equipe, delegando tarefas e fazendo perguntas para aproveitar a expertise uns dos outros. Quando `allow_delegation=True`, os agentes automaticamente têm acesso a poderosas ferramentas de colaboração.
|
||||
|
||||
## Guia Rápido: Habilite a Colaboração
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Task
|
||||
|
||||
# Enable collaboration for agents
|
||||
researcher = Agent(
|
||||
role="Research Specialist",
|
||||
goal="Conduct thorough research on any topic",
|
||||
backstory="Expert researcher with access to various sources",
|
||||
allow_delegation=True, # 🔑 Key setting for collaboration
|
||||
verbose=True
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role="Content Writer",
|
||||
goal="Create engaging content based on research",
|
||||
backstory="Skilled writer who transforms research into compelling content",
|
||||
allow_delegation=True, # 🔑 Enables asking questions to other agents
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Agents can now collaborate automatically
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[...],
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
## Como Funciona a Colaboração entre Agentes
|
||||
|
||||
Quando `allow_delegation=True`, o CrewAI automaticamente fornece aos agentes duas ferramentas poderosas:
|
||||
|
||||
### 1. **Ferramenta de Delegação de Trabalho**
|
||||
Permite que agentes designem tarefas para colegas com expertise específica.
|
||||
|
||||
```python
|
||||
# Agent automatically gets this tool:
|
||||
# Delegate work to coworker(task: str, context: str, coworker: str)
|
||||
```
|
||||
|
||||
### 2. **Ferramenta de Fazer Pergunta**
|
||||
Permite que agentes façam perguntas específicas para obter informações de colegas.
|
||||
|
||||
```python
|
||||
# Agent automatically gets this tool:
|
||||
# Ask question to coworker(question: str, context: str, coworker: str)
|
||||
```
|
||||
|
||||
## Colaboração em Ação
|
||||
|
||||
Veja um exemplo completo onde agentes colaboram em uma tarefa de criação de conteúdo:
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Task, Process
|
||||
|
||||
# Create collaborative agents
|
||||
researcher = Agent(
|
||||
role="Research Specialist",
|
||||
goal="Find accurate, up-to-date information on any topic",
|
||||
backstory="""You're a meticulous researcher with expertise in finding
|
||||
reliable sources and fact-checking information across various domains.""",
|
||||
allow_delegation=True,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role="Content Writer",
|
||||
goal="Create engaging, well-structured content",
|
||||
backstory="""You're a skilled content writer who excels at transforming
|
||||
research into compelling, readable content for different audiences.""",
|
||||
allow_delegation=True,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
editor = Agent(
|
||||
role="Content Editor",
|
||||
goal="Ensure content quality and consistency",
|
||||
backstory="""You're an experienced editor with an eye for detail,
|
||||
ensuring content meets high standards for clarity and accuracy.""",
|
||||
allow_delegation=True,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Create a task that encourages collaboration
|
||||
article_task = Task(
|
||||
description="""Write a comprehensive 1000-word article about 'The Future of AI in Healthcare'.
|
||||
|
||||
The article should include:
|
||||
- Current AI applications in healthcare
|
||||
- Emerging trends and technologies
|
||||
- Potential challenges and ethical considerations
|
||||
- Expert predictions for the next 5 years
|
||||
|
||||
Collaborate with your teammates to ensure accuracy and quality.""",
|
||||
expected_output="A well-researched, engaging 1000-word article with proper structure and citations",
|
||||
agent=writer # Writer leads, but can delegate research to researcher
|
||||
)
|
||||
|
||||
# Create collaborative crew
|
||||
crew = Crew(
|
||||
agents=[researcher, writer, editor],
|
||||
tasks=[article_task],
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
## Padrões de Colaboração
|
||||
|
||||
### Padrão 1: Pesquisa → Redação → Edição
|
||||
```python
|
||||
research_task = Task(
|
||||
description="Research the latest developments in quantum computing",
|
||||
expected_output="Comprehensive research summary with key findings and sources",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
writing_task = Task(
|
||||
description="Write an article based on the research findings",
|
||||
expected_output="Engaging 800-word article about quantum computing",
|
||||
agent=writer,
|
||||
context=[research_task] # Gets research output as context
|
||||
)
|
||||
|
||||
editing_task = Task(
|
||||
description="Edit and polish the article for publication",
|
||||
expected_output="Publication-ready article with improved clarity and flow",
|
||||
agent=editor,
|
||||
context=[writing_task] # Gets article draft as context
|
||||
)
|
||||
```
|
||||
|
||||
### Padrão 2: Tarefa Única Colaborativa
|
||||
```python
|
||||
collaborative_task = Task(
|
||||
description="""Create a marketing strategy for a new AI product.
|
||||
|
||||
Writer: Focus on messaging and content strategy
|
||||
Researcher: Provide market analysis and competitor insights
|
||||
|
||||
Work together to create a comprehensive strategy.""",
|
||||
expected_output="Complete marketing strategy with research backing",
|
||||
agent=writer # Lead agent, but can delegate to researcher
|
||||
)
|
||||
```
|
||||
|
||||
## Colaboração Hierárquica
|
||||
|
||||
Para projetos complexos, utilize um processo hierárquico com um agente gerente:
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Task, Process
|
||||
|
||||
# Manager agent coordinates the team
|
||||
manager = Agent(
|
||||
role="Project Manager",
|
||||
goal="Coordinate team efforts and ensure project success",
|
||||
backstory="Experienced project manager skilled at delegation and quality control",
|
||||
allow_delegation=True,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Specialist agents
|
||||
researcher = Agent(
|
||||
role="Researcher",
|
||||
goal="Provide accurate research and analysis",
|
||||
backstory="Expert researcher with deep analytical skills",
|
||||
allow_delegation=False, # Specialists focus on their expertise
|
||||
verbose=True
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role="Writer",
|
||||
goal="Create compelling content",
|
||||
backstory="Skilled writer who creates engaging content",
|
||||
allow_delegation=False,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Manager-led task
|
||||
project_task = Task(
|
||||
description="Create a comprehensive market analysis report with recommendations",
|
||||
expected_output="Executive summary, detailed analysis, and strategic recommendations",
|
||||
agent=manager # Manager will delegate to specialists
|
||||
)
|
||||
|
||||
# Hierarchical crew
|
||||
crew = Crew(
|
||||
agents=[manager, researcher, writer],
|
||||
tasks=[project_task],
|
||||
process=Process.hierarchical, # Manager coordinates everything
|
||||
manager_llm="gpt-4o", # Specify LLM for manager
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
## Melhores Práticas para Colaboração
|
||||
|
||||
### 1. **Definição Clara de Papéis**
|
||||
```python
|
||||
# ✅ Bom: papéis específicos e complementares
|
||||
researcher = Agent(role="Market Research Analyst", ...)
|
||||
writer = Agent(role="Technical Content Writer", ...)
|
||||
|
||||
# ❌ Evite: Papéis sobrepostos ou vagos
|
||||
agent1 = Agent(role="General Assistant", ...)
|
||||
agent2 = Agent(role="Helper", ...)
|
||||
```
|
||||
|
||||
### 2. **Delegação Estratégica Habilitada**
|
||||
```python
|
||||
# ✅ Habilite delegação para coordenadores e generalistas
|
||||
lead_agent = Agent(
|
||||
role="Content Lead",
|
||||
allow_delegation=True, # Can delegate to specialists
|
||||
...
|
||||
)
|
||||
|
||||
# ✅ Desative para especialistas focados (opcional)
|
||||
specialist_agent = Agent(
|
||||
role="Data Analyst",
|
||||
allow_delegation=False, # Focuses on core expertise
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
### 3. **Compartilhamento de Contexto**
|
||||
```python
|
||||
# ✅ Use o parâmetro context para dependências entre tarefas
|
||||
writing_task = Task(
|
||||
description="Write article based on research",
|
||||
agent=writer,
|
||||
context=[research_task], # Shares research results
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
### 4. **Descrições Claras de Tarefas**
|
||||
```python
|
||||
# ✅ Descrições específicas e acionáveis
|
||||
Task(
|
||||
description="""Research competitors in the AI chatbot space.
|
||||
Focus on: pricing models, key features, target markets.
|
||||
Provide data in a structured format.""",
|
||||
...
|
||||
)
|
||||
|
||||
# ❌ Descrições vagas que não orientam a colaboração
|
||||
Task(description="Do some research about chatbots", ...)
|
||||
```
|
||||
|
||||
## Solução de Problemas em Colaboração
|
||||
|
||||
### Problema: Agentes Não Colaboram
|
||||
**Sintomas:** Agentes trabalham isoladamente, sem ocorrer delegação
|
||||
```python
|
||||
# ✅ Solução: Certifique-se que a delegação está habilitada
|
||||
agent = Agent(
|
||||
role="...",
|
||||
allow_delegation=True, # This is required!
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
### Problema: Troca Excessiva de Perguntas
|
||||
**Sintomas:** Agentes fazem perguntas em excesso, progresso lento
|
||||
```python
|
||||
# ✅ Solução: Forneça melhor contexto e papéis específicos
|
||||
Task(
|
||||
description="""Write a technical blog post about machine learning.
|
||||
|
||||
Context: Target audience is software developers with basic ML knowledge.
|
||||
Length: 1200 words
|
||||
Include: code examples, practical applications, best practices
|
||||
|
||||
If you need specific technical details, delegate research to the researcher.""",
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
### Problema: Loops de Delegação
|
||||
**Sintomas:** Agentes delegam tarefas repetidamente uns para os outros indefinidamente
|
||||
```python
|
||||
# ✅ Solução: Hierarquia e responsabilidades bem definidas
|
||||
manager = Agent(role="Manager", allow_delegation=True)
|
||||
specialist1 = Agent(role="Specialist A", allow_delegation=False) # No re-delegation
|
||||
specialist2 = Agent(role="Specialist B", allow_delegation=False)
|
||||
```
|
||||
|
||||
## Recursos Avançados de Colaboração
|
||||
|
||||
### Regras Personalizadas de Colaboração
|
||||
```python
|
||||
# Set specific collaboration guidelines in agent backstory
|
||||
agent = Agent(
|
||||
role="Senior Developer",
|
||||
backstory="""You lead development projects and coordinate with team members.
|
||||
|
||||
Collaboration guidelines:
|
||||
- Delegate research tasks to the Research Analyst
|
||||
- Ask the Designer for UI/UX guidance
|
||||
- Consult the QA Engineer for testing strategies
|
||||
- Only escalate blocking issues to the Project Manager""",
|
||||
allow_delegation=True
|
||||
)
|
||||
```
|
||||
|
||||
### Monitoramento da Colaboração
|
||||
```python
|
||||
def track_collaboration(output):
|
||||
"""Track collaboration patterns"""
|
||||
if "Delegate work to coworker" in output.raw:
|
||||
print("🤝 Delegation occurred")
|
||||
if "Ask question to coworker" in output.raw:
|
||||
print("❓ Question asked")
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
step_callback=track_collaboration, # Monitor collaboration
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
## Memória e Aprendizado
|
||||
|
||||
Permita que agentes se lembrem de colaborações passadas:
|
||||
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Content Lead",
|
||||
memory=True, # Remembers past interactions
|
||||
allow_delegation=True,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
Com a memória ativada, os agentes aprendem com colaborações anteriores e aprimoram suas decisões de delegação ao longo do tempo.
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
- **Teste os exemplos**: Comece pelo exemplo básico de colaboração
|
||||
- **Experimente diferentes papéis**: Teste combinações variadas de papéis de agentes
|
||||
- **Monitore as interações**: Use `verbose=True` para ver a colaboração em ação
|
||||
- **Otimize descrições de tarefas**: Tarefas claras geram melhor colaboração
|
||||
- **Escale**: Experimente processos hierárquicos para projetos complexos
|
||||
|
||||
A colaboração transforma agentes de IA individuais em equipes poderosas capazes de enfrentar desafios complexos e multifacetados juntos.
|
||||
366
docs/pt-BR/concepts/crews.mdx
Normal file
366
docs/pt-BR/concepts/crews.mdx
Normal file
@@ -0,0 +1,366 @@
|
||||
---
|
||||
title: Crews
|
||||
description: Compreendendo e utilizando crews no framework crewAI com atributos e funcionalidades abrangentes.
|
||||
icon: people-group
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Uma crew no crewAI representa um grupo colaborativo de agentes trabalhando em conjunto para alcançar um conjunto de tarefas. Cada crew define a estratégia de execução de tarefas, colaboração entre agentes e o fluxo de trabalho geral.
|
||||
|
||||
## Atributos de Crew
|
||||
|
||||
| Atributo | Parâmetros | Descrição |
|
||||
| :------------------------------------ | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Tasks** | `tasks` | Uma lista de tasks atribuídas à crew. |
|
||||
| **Agents** | `agents` | Uma lista de agentes que fazem parte da crew. |
|
||||
| **Process** _(opcional)_ | `process` | O fluxo de processo (por exemplo, sequencial, hierárquico) seguido pela crew. O padrão é `sequential`. |
|
||||
| **Verbose** _(opcional)_ | `verbose` | O nível de verbosidade para logging durante a execução. O padrão é `False`. |
|
||||
| **Manager LLM** _(opcional)_ | `manager_llm` | O modelo de linguagem utilizado pelo agente gerenciador em um processo hierárquico. **Obrigatório ao usar um processo hierárquico.** |
|
||||
| **Function Calling LLM** _(opcional)_ | `function_calling_llm` | Se definido, a crew utilizará este LLM para invocar funções das ferramentas para todos os agentes da crew. Cada agente pode ter seu próprio LLM, que substitui o LLM da crew para chamadas de função. |
|
||||
| **Config** _(opcional)_ | `config` | Configurações opcionais para a crew, no formato `Json` ou `Dict[str, Any]`. |
|
||||
| **Max RPM** _(opcional)_ | `max_rpm` | Número máximo de requisições por minuto que a crew respeita durante a execução. O padrão é `None`. |
|
||||
| **Memory** _(opcional)_ | `memory` | Utilizada para armazenar memórias de execução (curto prazo, longo prazo, memória de entidade). |
|
||||
| **Memory Config** _(opcional)_ | `memory_config` | Configuração para o provedor de memória a ser utilizada pela crew. |
|
||||
| **Cache** _(opcional)_ | `cache` | Especifica se deve usar cache para armazenar os resultados da execução de ferramentas. O padrão é `True`. |
|
||||
| **Embedder** _(opcional)_ | `embedder` | Configuração do embedder a ser utilizado pela crew. Atualmente mais usado por memory. O padrão é `{"provider": "openai"}`. |
|
||||
| **Step Callback** _(opcional)_ | `step_callback` | Uma função chamada após cada etapa de cada agente. Pode ser usada para registrar as ações do agente ou executar outras operações; não sobrescreve o `step_callback` específico do agente. |
|
||||
| **Task Callback** _(opcional)_ | `task_callback` | Uma função chamada após a conclusão de cada tarefa. Útil para monitoramento ou para operações adicionais pós-execução da task. |
|
||||
| **Share Crew** _(opcional)_ | `share_crew` | Se deseja compartilhar as informações completas da crew e execução com a equipe do crewAI para melhorar a biblioteca e nos permitir treinar modelos. |
|
||||
| **Output Log File** _(opcional)_ | `output_log_file` | Defina como True para salvar logs como logs.txt no diretório atual ou forneça um caminho de arquivo. Os logs estarão em formato JSON se o nome terminar com .json, caso contrário .txt. O padrão é `None`. |
|
||||
| **Manager Agent** _(opcional)_ | `manager_agent` | `manager` define um agente customizado que será utilizado como gerente. |
|
||||
| **Prompt File** _(opcional)_ | `prompt_file` | Caminho para o arquivo JSON de prompt a ser utilizado pela crew. |
|
||||
| **Planning** *(opcional)* | `planning` | Adiciona habilidade de planejamento à Crew. Quando ativado, antes de cada iteração, todos os dados da Crew são enviados a um AgentPlanner que planejará as tasks e este plano será adicionado à descrição de cada task. |
|
||||
| **Planning LLM** *(opcional)* | `planning_llm` | O modelo de linguagem usado pelo AgentPlanner em um processo de planejamento. |
|
||||
|
||||
<Tip>
|
||||
**Crew Max RPM**: O atributo `max_rpm` define o número máximo de requisições por minuto que a crew pode executar para evitar limites de taxa e irá sobrescrever as configurações de `max_rpm` dos agentes individuais se você o definir.
|
||||
</Tip>
|
||||
|
||||
## Criando Crews
|
||||
|
||||
Existem duas maneiras de criar crews no CrewAI: utilizando **configuração YAML (recomendado)** ou definindo diretamente **em código**.
|
||||
|
||||
### Configuração YAML (Recomendado)
|
||||
|
||||
O uso da configuração YAML proporciona uma forma mais limpa e fácil de manter para definir crews, sendo consistente com a definição de agentes e tasks em projetos CrewAI.
|
||||
|
||||
Após criar seu projeto CrewAI conforme descrito na seção [Instalação](/pt-BR/installation), você pode definir sua crew em uma classe que herda de `CrewBase` e utiliza decorators para definir agentes, tarefas e a própria crew.
|
||||
|
||||
#### Exemplo de Classe Crew com Decorators
|
||||
|
||||
```python code
|
||||
from crewai import Agent, Crew, Task, Process
|
||||
from crewai.project import CrewBase, agent, task, crew, before_kickoff, after_kickoff
|
||||
from crewai.agents.agent_builder.base_agent import BaseAgent
|
||||
from typing import List
|
||||
|
||||
@CrewBase
|
||||
class YourCrewName:
|
||||
"""Descrição da sua crew"""
|
||||
|
||||
agents: List[BaseAgent]
|
||||
tasks: List[Task]
|
||||
|
||||
# Caminhos para seus arquivos de configuração YAML
|
||||
# Para um exemplo de agente e tarefa definidos em YAML, confira:
|
||||
# - Task: https://docs.crewai.com/concepts/tasks#yaml-configuration-recommended
|
||||
# - Agents: https://docs.crewai.com/concepts/agents#yaml-configuration-recommended
|
||||
agents_config = 'config/agents.yaml'
|
||||
tasks_config = 'config/tasks.yaml'
|
||||
|
||||
@before_kickoff
|
||||
def prepare_inputs(self, inputs):
|
||||
# Modifique inputs antes da crew iniciar
|
||||
inputs['additional_data'] = "Alguma informação extra"
|
||||
return inputs
|
||||
|
||||
@after_kickoff
|
||||
def process_output(self, output):
|
||||
# Modifique a saída após a crew finalizar
|
||||
output.raw += "\nProcessado após kickoff."
|
||||
return output
|
||||
|
||||
@agent
|
||||
def agent_one(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['agent_one'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
@agent
|
||||
def agent_two(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['agent_two'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
@task
|
||||
def task_one(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['task_one'] # type: ignore[index]
|
||||
)
|
||||
|
||||
@task
|
||||
def task_two(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['task_two'] # type: ignore[index]
|
||||
)
|
||||
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=self.agents, # Coletado automaticamente pelo decorator @agent
|
||||
tasks=self.tasks, # Coletado automaticamente pelo decorator @task
|
||||
process=Process.sequential,
|
||||
verbose=True,
|
||||
)
|
||||
```
|
||||
|
||||
Como executar o código acima:
|
||||
|
||||
```python code
|
||||
YourCrewName().crew().kickoff(inputs={"any": "input here"})
|
||||
```
|
||||
|
||||
<Note>
|
||||
As tarefas serão executadas na ordem em que forem definidas.
|
||||
</Note>
|
||||
|
||||
A classe `CrewBase`, junto com esses decorators, automatiza a coleta de agentes e tarefas, reduzindo a necessidade de gerenciamento manual.
|
||||
|
||||
#### Visão geral dos Decorators de `annotations.py`
|
||||
|
||||
O CrewAI fornece vários decorators no arquivo `annotations.py` que são usados para marcar métodos dentro de sua classe crew para tratamento especial:
|
||||
|
||||
- `@CrewBase`: Marca a classe como classe base de crew.
|
||||
- `@agent`: Denota um método que retorna um objeto `Agent`.
|
||||
- `@task`: Denota um método que retorna um objeto `Task`.
|
||||
- `@crew`: Denota o método que retorna o objeto `Crew`.
|
||||
- `@before_kickoff`: (Opcional) Marca um método a ser executado antes da crew iniciar.
|
||||
- `@after_kickoff`: (Opcional) Marca um método a ser executado após a crew finalizar.
|
||||
|
||||
Esses decorators ajudam na organização da estrutura da sua crew e coletam automaticamente agentes e tasks sem precisar listá-los manualmente.
|
||||
|
||||
### Definição Direta em Código (Alternativa)
|
||||
|
||||
Como alternativa, você pode definir a crew diretamente em código sem utilizar arquivos de configuração YAML.
|
||||
|
||||
```python code
|
||||
from crewai import Agent, Crew, Task, Process
|
||||
from crewai_tools import YourCustomTool
|
||||
|
||||
class YourCrewName:
|
||||
def agent_one(self) -> Agent:
|
||||
return Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze data trends in the market",
|
||||
backstory="An experienced data analyst with a background in economics",
|
||||
verbose=True,
|
||||
tools=[YourCustomTool()]
|
||||
)
|
||||
|
||||
def agent_two(self) -> Agent:
|
||||
return Agent(
|
||||
role="Market Researcher",
|
||||
goal="Gather information on market dynamics",
|
||||
backstory="A diligent researcher with a keen eye for detail",
|
||||
verbose=True
|
||||
)
|
||||
|
||||
def task_one(self) -> Task:
|
||||
return Task(
|
||||
description="Collect recent market data and identify trends.",
|
||||
expected_output="A report summarizing key trends in the market.",
|
||||
agent=self.agent_one()
|
||||
)
|
||||
|
||||
def task_two(self) -> Task:
|
||||
return Task(
|
||||
description="Research factors affecting market dynamics.",
|
||||
expected_output="An analysis of factors influencing the market.",
|
||||
agent=self.agent_two()
|
||||
)
|
||||
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=[self.agent_one(), self.agent_two()],
|
||||
tasks=[self.task_one(), self.task_two()],
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
Como executar o código acima:
|
||||
|
||||
```python code
|
||||
YourCrewName().crew().kickoff(inputs={})
|
||||
```
|
||||
|
||||
Neste exemplo:
|
||||
|
||||
- Agentes e tarefas são definidos diretamente dentro da classe, sem decorators.
|
||||
- Criamos e gerenciamos manualmente a lista de agentes e tasks.
|
||||
- Essa abordagem fornece mais controle, mas pode ser menos sustentável para projetos maiores.
|
||||
|
||||
## Saída da Crew
|
||||
|
||||
A saída de uma crew no framework CrewAI é encapsulada na classe `CrewOutput`.
|
||||
Essa classe fornece uma forma estruturada de acessar os resultados da execução da crew, incluindo vários formatos como string bruta, JSON e modelos Pydantic.
|
||||
O `CrewOutput` inclui os resultados da tarefa final, uso de tokens e as saídas das tasks individuais.
|
||||
|
||||
### Atributos do Crew Output
|
||||
|
||||
| Atributo | Parâmetros | Tipo | Descrição |
|
||||
| :--------------- | :------------- | :------------------------ | :------------------------------------------------------------------------------------------------ |
|
||||
| **Raw** | `raw` | `str` | A saída bruta da crew. Este é o formato padrão da saída. |
|
||||
| **Pydantic** | `pydantic` | `Optional[BaseModel]` | Um objeto modelo Pydantic representando a saída estruturada da crew. |
|
||||
| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]`| Um dicionário representando a saída da crew em formato JSON. |
|
||||
| **Tasks Output** | `tasks_output` | `List[TaskOutput]` | Uma lista de objetos `TaskOutput`, cada um representando a saída de uma task na crew. |
|
||||
| **Token Usage** | `token_usage` | `Dict[str, Any]` | Um resumo do uso de tokens, oferecendo informações sobre a performance do modelo de linguagem. |
|
||||
|
||||
### Métodos e Propriedades do Crew Output
|
||||
|
||||
| Método/Propriedade | Descrição |
|
||||
| :----------------- | :------------------------------------------------------------------------------------------------- |
|
||||
| **json** | Retorna a representação em string JSON da saída da crew caso o formato seja JSON. |
|
||||
| **to_dict** | Converte as saídas JSON e Pydantic em um dicionário. |
|
||||
| **__str__** | Retorna a representação em string do resultado da crew, priorizando Pydantic, depois JSON, depois raw.|
|
||||
|
||||
### Acessando a Saída da Crew
|
||||
|
||||
Após executar uma crew, sua saída pode ser acessada pelo atributo `output` do objeto `Crew`. A classe `CrewOutput` oferece várias formas de interagir com esta saída.
|
||||
|
||||
#### Exemplo
|
||||
|
||||
```python Code
|
||||
# Execução de exemplo da crew
|
||||
crew = Crew(
|
||||
agents=[research_agent, writer_agent],
|
||||
tasks=[research_task, write_article_task],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
crew_output = crew.kickoff()
|
||||
|
||||
# Acessando a saída da crew
|
||||
print(f"Raw Output: {crew_output.raw}")
|
||||
if crew_output.json_dict:
|
||||
print(f"JSON Output: {json.dumps(crew_output.json_dict, indent=2)}")
|
||||
if crew_output.pydantic:
|
||||
print(f"Pydantic Output: {crew_output.pydantic}")
|
||||
print(f"Tasks Output: {crew_output.tasks_output}")
|
||||
print(f"Token Usage: {crew_output.token_usage}")
|
||||
```
|
||||
|
||||
## Acessando Logs da Crew
|
||||
|
||||
Você pode visualizar o log em tempo real da execução da crew, definindo `output_log_file` como `True(Boolean)` ou um `file_name(str)`. Suporta logging de eventos como tanto `file_name.txt` quanto `file_name.json`.
|
||||
Se for `True(Boolean)`, salvará como `logs.txt`.
|
||||
|
||||
Caso `output_log_file` seja `False(Boolean)` ou `None`, os logs não serão gerados.
|
||||
|
||||
```python Code
|
||||
# Salvar logs da crew
|
||||
crew = Crew(output_log_file = True) # Logs serão salvos como logs.txt
|
||||
crew = Crew(output_log_file = file_name) # Logs serão salvos como file_name.txt
|
||||
crew = Crew(output_log_file = file_name.txt) # Logs serão salvos como file_name.txt
|
||||
crew = Crew(output_log_file = file_name.json) # Logs serão salvos como file_name.json
|
||||
```
|
||||
|
||||
## Utilização de Memória
|
||||
|
||||
As crews podem utilizar memória (curto prazo, longo prazo e memória de entidade) para potencializar sua execução e aprendizado ao longo do tempo. Este recurso permite que as crews armazenem e recuperem memórias de execução, auxiliando na tomada de decisão e nas estratégias de execução de tasks.
|
||||
|
||||
## Utilização de Cache
|
||||
|
||||
Caches podem ser utilizados para armazenar resultados de execuções de ferramentas, tornando o processo mais eficiente ao evitar a reexecução de tasks idênticas.
|
||||
|
||||
## Métricas de Uso da Crew
|
||||
|
||||
Após a execução da crew, você pode acessar o atributo `usage_metrics` para visualizar as métricas de uso do modelo de linguagem (LLM) para todas as tasks executadas pela crew. Isso fornece insights sobre eficiência operacional e oportunidades de melhoria.
|
||||
|
||||
```python Code
|
||||
# Acessar as métricas de uso da crew
|
||||
crew = Crew(agents=[agent1, agent2], tasks=[task1, task2])
|
||||
crew.kickoff()
|
||||
print(crew.usage_metrics)
|
||||
```
|
||||
|
||||
## Processo de Execução da Crew
|
||||
|
||||
- **Sequential Process**: As tasks são executadas uma após a outra, permitindo um fluxo de trabalho linear.
|
||||
- **Hierarchical Process**: Um agente gerente coordena a crew, delegando tarefas e validando resultados antes de prosseguir. **Nota**: Um `manager_llm` ou `manager_agent` é necessário para este processo e é essencial para validar o fluxo.
|
||||
|
||||
### Iniciando uma Crew
|
||||
|
||||
Uma vez que sua crew esteja montada, inicie o workflow com o método `kickoff()`. Isso inicia a execução conforme o fluxo de processo definido.
|
||||
|
||||
```python Code
|
||||
# Iniciar execução das tasks da crew
|
||||
result = my_crew.kickoff()
|
||||
print(result)
|
||||
```
|
||||
|
||||
### Diferentes Formas de Iniciar uma Crew
|
||||
|
||||
Assim que sua crew estiver definida, inicie o fluxo de trabalho com o método kickoff apropriado. O CrewAI oferece vários métodos para melhor controle do processo: `kickoff()`, `kickoff_for_each()`, `kickoff_async()` e `kickoff_for_each_async()`.
|
||||
|
||||
- `kickoff()`: Inicia o processo de execução seguindo o fluxo definido.
|
||||
- `kickoff_for_each()`: Executa tasks sequencialmente para cada evento de entrada ou item da coleção fornecida.
|
||||
- `kickoff_async()`: Inicia o workflow de forma assíncrona.
|
||||
- `kickoff_for_each_async()`: Executa as tasks concorrentemente para cada entrada, aproveitando o processamento assíncrono.
|
||||
|
||||
```python Code
|
||||
# Iniciar execução das tasks da crew
|
||||
result = my_crew.kickoff()
|
||||
print(result)
|
||||
|
||||
# Exemplo com kickoff_for_each
|
||||
inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}]
|
||||
results = my_crew.kickoff_for_each(inputs=inputs_array)
|
||||
for result in results:
|
||||
print(result)
|
||||
|
||||
# Exemplo com kickoff_async
|
||||
inputs = {'topic': 'AI in healthcare'}
|
||||
async_result = await my_crew.kickoff_async(inputs=inputs)
|
||||
print(async_result)
|
||||
|
||||
# Exemplo com kickoff_for_each_async
|
||||
inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}]
|
||||
async_results = await my_crew.kickoff_for_each_async(inputs=inputs_array)
|
||||
for async_result in async_results:
|
||||
print(async_result)
|
||||
```
|
||||
|
||||
Esses métodos fornecem flexibilidade para gerenciar e executar tasks dentro de sua crew, permitindo fluxos de trabalho síncronos e assíncronos de acordo com sua necessidade.
|
||||
|
||||
### Repetindo Execução a partir de uma Task Específica
|
||||
|
||||
Agora é possível reiniciar a execução a partir de uma task específica usando o comando CLI `replay`.
|
||||
|
||||
O recurso de replay no CrewAI permite reexecutar a partir de uma task específica através da interface de linha de comando (CLI). Rodando o comando `crewai replay -t <task_id>`, você pode especificar o `task_id` para o processo de replay.
|
||||
|
||||
Kickoffs agora salvam localmente as saídas das tasks dos kickoffs recentes para permitir replay posteriormente.
|
||||
|
||||
### Repetindo a Partir de uma Task Específica Usando o CLI
|
||||
|
||||
Para usar o recurso de replay, siga estes passos:
|
||||
|
||||
1. Abra seu terminal ou prompt de comando.
|
||||
2. Navegue até o diretório do seu projeto CrewAI.
|
||||
3. Execute o seguinte comando:
|
||||
|
||||
Para visualizar os IDs das últimas tasks do kickoff, utilize:
|
||||
|
||||
```shell
|
||||
crewai log-tasks-outputs
|
||||
```
|
||||
|
||||
Depois, para repetir a partir de uma task específica, utilize:
|
||||
|
||||
```shell
|
||||
crewai replay -t <task_id>
|
||||
```
|
||||
|
||||
Esses comandos permitem repetir tasks dos seus últimos kickoffs, mantendo o contexto das tasks já executadas anteriormente.
|
||||
379
docs/pt-BR/concepts/event-listener.mdx
Normal file
379
docs/pt-BR/concepts/event-listener.mdx
Normal file
@@ -0,0 +1,379 @@
|
||||
---
|
||||
title: 'Listeners de Evento'
|
||||
description: 'Acesse eventos do CrewAI para criar integrações e monitoramento personalizados'
|
||||
icon: spinner
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O CrewAI oferece um sistema de eventos poderoso que permite escutar e reagir a diversos eventos que ocorrem durante a execução do seu Crew. Esse recurso possibilita a criação de integrações personalizadas, soluções de monitoramento, sistemas de log ou qualquer outra funcionalidade que precise ser acionada com base nos eventos internos do CrewAI.
|
||||
|
||||
## Como Funciona
|
||||
|
||||
O CrewAI utiliza uma arquitetura de event bus para emitir eventos ao longo do ciclo de vida da execução. O sistema de eventos é construído a partir dos seguintes componentes:
|
||||
|
||||
1. **CrewAIEventsBus**: Um event bus singleton que gerencia o registro e emissão de eventos
|
||||
2. **BaseEvent**: Classe base para todos os eventos do sistema
|
||||
3. **BaseEventListener**: Classe base abstrata para criar listeners de evento personalizados
|
||||
|
||||
Quando ações específicas ocorrem no CrewAI (como a inicialização de um Crew, um Agent concluindo uma tarefa ou o uso de uma ferramenta), o sistema emite os eventos correspondentes. Você pode registrar handlers para esses eventos para executar código personalizado quando eles acontecerem.
|
||||
|
||||
<Note type="info" title="Aprimoramento Enterprise: Prompt Tracing">
|
||||
O CrewAI Enterprise fornece o recurso Prompt Tracing, que aproveita o sistema de eventos para rastrear, armazenar e visualizar todos os prompts, respostas e metadados associados. Isso proporciona poderosas capacidades de depuração e transparência nas operações dos seus agentes.
|
||||
|
||||
|
||||
|
||||
Com o Prompt Tracing você pode:
|
||||
- Visualizar o histórico completo de todos os prompts enviados ao seu LLM
|
||||
- Monitorar o uso de tokens e custos
|
||||
- Depurar falhas de raciocínio dos agentes
|
||||
- Compartilhar sequências de prompts com sua equipe
|
||||
- Comparar diferentes estratégias de prompts
|
||||
- Exportar rastreamentos para compliance e auditoria
|
||||
</Note>
|
||||
|
||||
## Criando um Listener de Evento Personalizado
|
||||
|
||||
Para criar um listener de evento personalizado, você precisa:
|
||||
|
||||
1. Criar uma classe que herde de `BaseEventListener`
|
||||
2. Implementar o método `setup_listeners`
|
||||
3. Registrar handles para os eventos de seu interesse
|
||||
4. Instanciar seu listener no arquivo apropriado
|
||||
|
||||
Veja um exemplo simples de uma classe de listener de evento personalizado:
|
||||
|
||||
```python
|
||||
from crewai.utilities.events import (
|
||||
CrewKickoffStartedEvent,
|
||||
CrewKickoffCompletedEvent,
|
||||
AgentExecutionCompletedEvent,
|
||||
)
|
||||
from crewai.utilities.events.base_event_listener import BaseEventListener
|
||||
|
||||
class MyCustomListener(BaseEventListener):
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
|
||||
def setup_listeners(self, crewai_event_bus):
|
||||
@crewai_event_bus.on(CrewKickoffStartedEvent)
|
||||
def on_crew_started(source, event):
|
||||
print(f"Crew '{event.crew_name}' has started execution!")
|
||||
|
||||
@crewai_event_bus.on(CrewKickoffCompletedEvent)
|
||||
def on_crew_completed(source, event):
|
||||
print(f"Crew '{event.crew_name}' has completed execution!")
|
||||
print(f"Output: {event.output}")
|
||||
|
||||
@crewai_event_bus.on(AgentExecutionCompletedEvent)
|
||||
def on_agent_execution_completed(source, event):
|
||||
print(f"Agent '{event.agent.role}' completed task")
|
||||
print(f"Output: {event.output}")
|
||||
```
|
||||
|
||||
## Registrando Corretamente Seu Listener
|
||||
|
||||
Apenas definir sua classe de listener não é suficiente. É necessário criar uma instância dela e garantir que ela seja importada na sua aplicação. Isso garante que:
|
||||
|
||||
1. Os event handlers estejam registrados no event bus
|
||||
2. A instância do listener permaneça em memória (não seja coletada pelo garbage collector)
|
||||
3. O listener esteja ativo quando os eventos forem emitidos
|
||||
|
||||
### Opção 1: Importar e Instanciar no Seu Crew ou Implementação de Flow
|
||||
|
||||
O mais importante é criar uma instância do seu listener no arquivo onde seu Crew ou Flow está definido e executado:
|
||||
|
||||
#### Para Aplicações Baseadas em Crew
|
||||
|
||||
Crie e importe seu listener no início do arquivo de implementação do seu Crew:
|
||||
|
||||
```python
|
||||
# No seu arquivo crew.py
|
||||
from crewai import Agent, Crew, Task
|
||||
from my_listeners import MyCustomListener
|
||||
|
||||
# Crie uma instância do seu listener
|
||||
my_listener = MyCustomListener()
|
||||
|
||||
class MyCustomCrew:
|
||||
# Sua implementação do crew...
|
||||
|
||||
def crew(self):
|
||||
return Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
# ...
|
||||
)
|
||||
```
|
||||
|
||||
#### Para Aplicações Baseadas em Flow
|
||||
|
||||
Crie e importe seu listener no início do arquivo de implementação do seu Flow:
|
||||
|
||||
```python
|
||||
# Em seu arquivo main.py ou flow.py
|
||||
from crewai.flow import Flow, listen, start
|
||||
from my_listeners import MyCustomListener
|
||||
|
||||
# Crie uma instância do seu listener
|
||||
my_listener = MyCustomListener()
|
||||
|
||||
class MyCustomFlow(Flow):
|
||||
# Sua implementação do flow...
|
||||
|
||||
@start()
|
||||
def first_step(self):
|
||||
# ...
|
||||
```
|
||||
|
||||
Isso assegura que seu listener será carregado e estará ativo quando seu Crew ou Flow for executado.
|
||||
|
||||
### Opção 2: Criar um Pacote para Seus Listeners
|
||||
|
||||
Para uma abordagem mais estruturada, especialmente se houver múltiplos listeners:
|
||||
|
||||
1. Crie um pacote para seus listeners:
|
||||
|
||||
```
|
||||
my_project/
|
||||
├── listeners/
|
||||
│ ├── __init__.py
|
||||
│ ├── my_custom_listener.py
|
||||
│ └── another_listener.py
|
||||
```
|
||||
|
||||
2. Em `my_custom_listener.py`, defina sua classe de listener e crie uma instância:
|
||||
|
||||
```python
|
||||
# my_custom_listener.py
|
||||
from crewai.utilities.events.base_event_listener import BaseEventListener
|
||||
# ... importe events ...
|
||||
|
||||
class MyCustomListener(BaseEventListener):
|
||||
# ... implementação ...
|
||||
|
||||
# Crie uma instância do seu listener
|
||||
my_custom_listener = MyCustomListener()
|
||||
```
|
||||
|
||||
3. Em `__init__.py`, importe as instâncias dos listeners para garantir seu carregamento:
|
||||
|
||||
```python
|
||||
# __init__.py
|
||||
from .my_custom_listener import my_custom_listener
|
||||
from .another_listener import another_listener
|
||||
|
||||
# Opcionalmente exporte-os se precisar acessá-los em outros lugares
|
||||
__all__ = ['my_custom_listener', 'another_listener']
|
||||
```
|
||||
|
||||
4. Importe seu pacote de listeners no arquivo do seu Crew ou Flow:
|
||||
|
||||
```python
|
||||
# No seu arquivo crew.py ou flow.py
|
||||
import my_project.listeners # Isso carrega todos os seus listeners
|
||||
|
||||
class MyCustomCrew:
|
||||
# Sua implementação do crew...
|
||||
```
|
||||
|
||||
É exatamente assim que o `agentops_listener` integrado do CrewAI é registrado. No código-fonte do CrewAI, você encontrará:
|
||||
|
||||
```python
|
||||
# src/crewai/utilities/events/third_party/__init__.py
|
||||
from .agentops_listener import agentops_listener
|
||||
```
|
||||
|
||||
Isso garante que o `agentops_listener` seja carregado quando o pacote `crewai.utilities.events` for importado.
|
||||
|
||||
## Tipos de Eventos Disponíveis
|
||||
|
||||
O CrewAI fornece uma ampla variedade de eventos para escuta:
|
||||
|
||||
### Eventos de Crew
|
||||
|
||||
- **CrewKickoffStartedEvent**: Emitido quando um Crew inicia a execução
|
||||
- **CrewKickoffCompletedEvent**: Emitido quando um Crew conclui a execução
|
||||
- **CrewKickoffFailedEvent**: Emitido quando um Crew falha ao concluir a execução
|
||||
- **CrewTestStartedEvent**: Emitido ao iniciar o teste de um Crew
|
||||
- **CrewTestCompletedEvent**: Emitido ao concluir o teste de um Crew
|
||||
- **CrewTestFailedEvent**: Emitido ao falhar no teste de um Crew
|
||||
- **CrewTrainStartedEvent**: Emitido ao iniciar o treinamento de um Crew
|
||||
- **CrewTrainCompletedEvent**: Emitido ao concluir o treinamento de um Crew
|
||||
- **CrewTrainFailedEvent**: Emitido ao falhar no treinamento de um Crew
|
||||
|
||||
### Eventos de Agent
|
||||
|
||||
- **AgentExecutionStartedEvent**: Emitido quando um Agent inicia a execução de uma tarefa
|
||||
- **AgentExecutionCompletedEvent**: Emitido quando um Agent conclui a execução de uma tarefa
|
||||
- **AgentExecutionErrorEvent**: Emitido quando um Agent encontra um erro durante a execução
|
||||
|
||||
### Eventos de Task
|
||||
|
||||
- **TaskStartedEvent**: Emitido ao iniciar a execução de uma Task
|
||||
- **TaskCompletedEvent**: Emitido ao concluir a execução de uma Task
|
||||
- **TaskFailedEvent**: Emitido ao falhar na execução de uma Task
|
||||
- **TaskEvaluationEvent**: Emitido quando uma Task é avaliada
|
||||
|
||||
### Eventos de Uso de Ferramentas
|
||||
|
||||
- **ToolUsageStartedEvent**: Emitido ao iniciar a execução de uma ferramenta
|
||||
- **ToolUsageFinishedEvent**: Emitido ao concluir a execução de uma ferramenta
|
||||
- **ToolUsageErrorEvent**: Emitido quando ocorre erro na execução de uma ferramenta
|
||||
- **ToolValidateInputErrorEvent**: Emitido ao ocorrer erro de validação de entrada na ferramenta
|
||||
- **ToolExecutionErrorEvent**: Emitido quando ocorre erro na execução de uma ferramenta
|
||||
- **ToolSelectionErrorEvent**: Emitido ao ocorrer erro na seleção de uma ferramenta
|
||||
|
||||
### Eventos de Knowledge
|
||||
|
||||
- **KnowledgeRetrievalStartedEvent**: Emitido ao iniciar recuperação de conhecimento
|
||||
- **KnowledgeRetrievalCompletedEvent**: Emitido ao concluir recuperação de conhecimento
|
||||
- **KnowledgeQueryStartedEvent**: Emitido ao iniciar consulta de conhecimento
|
||||
- **KnowledgeQueryCompletedEvent**: Emitido ao concluir consulta de conhecimento
|
||||
- **KnowledgeQueryFailedEvent**: Emitido ao falhar consulta de conhecimento
|
||||
- **KnowledgeSearchQueryFailedEvent**: Emitido ao falhar consulta de busca de conhecimento
|
||||
|
||||
### Eventos de Guardrail do LLM
|
||||
|
||||
- **LLMGuardrailStartedEvent**: Emitido ao iniciar validação dos guardrails. Contém detalhes do guardrail aplicado e tentativas.
|
||||
- **LLMGuardrailCompletedEvent**: Emitido ao concluir validação dos guardrails. Contém detalhes sobre sucesso/falha na validação, resultados e mensagens de erro, se houver.
|
||||
|
||||
### Eventos de Flow
|
||||
|
||||
- **FlowCreatedEvent**: Emitido ao criar um Flow
|
||||
- **FlowStartedEvent**: Emitido ao iniciar a execução de um Flow
|
||||
- **FlowFinishedEvent**: Emitido ao concluir a execução de um Flow
|
||||
- **FlowPlotEvent**: Emitido ao plotar um Flow
|
||||
- **MethodExecutionStartedEvent**: Emitido ao iniciar a execução de um método do Flow
|
||||
- **MethodExecutionFinishedEvent**: Emitido ao concluir a execução de um método do Flow
|
||||
- **MethodExecutionFailedEvent**: Emitido ao falhar na execução de um método do Flow
|
||||
|
||||
### Eventos de LLM
|
||||
|
||||
- **LLMCallStartedEvent**: Emitido ao iniciar uma chamada LLM
|
||||
- **LLMCallCompletedEvent**: Emitido ao concluir uma chamada LLM
|
||||
- **LLMCallFailedEvent**: Emitido ao falhar uma chamada LLM
|
||||
- **LLMStreamChunkEvent**: Emitido para cada chunk recebido durante respostas em streaming do LLM
|
||||
|
||||
## Estrutura dos Handlers de Evento
|
||||
|
||||
Cada handler de evento recebe dois parâmetros:
|
||||
|
||||
1. **source**: O objeto que emitiu o evento
|
||||
2. **event**: A instância do evento, contendo dados específicos do evento
|
||||
|
||||
A estrutura do objeto de evento depende do tipo do evento, mas todos herdam de `BaseEvent` e incluem:
|
||||
|
||||
- **timestamp**: O horário em que o evento foi emitido
|
||||
- **type**: Identificador do tipo do evento
|
||||
|
||||
Campos adicionais variam pelo tipo de evento. Por exemplo, `CrewKickoffCompletedEvent` inclui os campos `crew_name` e `output`.
|
||||
|
||||
## Exemplo Real: Integração com AgentOps
|
||||
|
||||
O CrewAI inclui um exemplo de integração com [AgentOps](https://github.com/AgentOps-AI/agentops), uma plataforma de monitoramento e observabilidade para agentes de IA. Veja como é implementado:
|
||||
|
||||
```python
|
||||
from typing import Optional
|
||||
|
||||
from crewai.utilities.events import (
|
||||
CrewKickoffCompletedEvent,
|
||||
ToolUsageErrorEvent,
|
||||
ToolUsageStartedEvent,
|
||||
)
|
||||
from crewai.utilities.events.base_event_listener import BaseEventListener
|
||||
from crewai.utilities.events.crew_events import CrewKickoffStartedEvent
|
||||
from crewai.utilities.events.task_events import TaskEvaluationEvent
|
||||
|
||||
try:
|
||||
import agentops
|
||||
AGENTOPS_INSTALLED = True
|
||||
except ImportError:
|
||||
AGENTOPS_INSTALLED = False
|
||||
|
||||
class AgentOpsListener(BaseEventListener):
|
||||
tool_event: Optional["agentops.ToolEvent"] = None
|
||||
session: Optional["agentops.Session"] = None
|
||||
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
|
||||
def setup_listeners(self, crewai_event_bus):
|
||||
if not AGENTOPS_INSTALLED:
|
||||
return
|
||||
|
||||
@crewai_event_bus.on(CrewKickoffStartedEvent)
|
||||
def on_crew_kickoff_started(source, event: CrewKickoffStartedEvent):
|
||||
self.session = agentops.init()
|
||||
for agent in source.agents:
|
||||
if self.session:
|
||||
self.session.create_agent(
|
||||
name=agent.role,
|
||||
agent_id=str(agent.id),
|
||||
)
|
||||
|
||||
@crewai_event_bus.on(CrewKickoffCompletedEvent)
|
||||
def on_crew_kickoff_completed(source, event: CrewKickoffCompletedEvent):
|
||||
if self.session:
|
||||
self.session.end_session(
|
||||
end_state="Success",
|
||||
end_state_reason="Finished Execution",
|
||||
)
|
||||
|
||||
@crewai_event_bus.on(ToolUsageStartedEvent)
|
||||
def on_tool_usage_started(source, event: ToolUsageStartedEvent):
|
||||
self.tool_event = agentops.ToolEvent(name=event.tool_name)
|
||||
if self.session:
|
||||
self.session.record(self.tool_event)
|
||||
|
||||
@crewai_event_bus.on(ToolUsageErrorEvent)
|
||||
def on_tool_usage_error(source, event: ToolUsageErrorEvent):
|
||||
agentops.ErrorEvent(exception=event.error, trigger_event=self.tool_event)
|
||||
```
|
||||
|
||||
Esse listener inicializa uma sessão do AgentOps quando um Crew inicia, cadastra agentes no AgentOps, rastreia o uso de ferramentas e finaliza a sessão quando o Crew é concluído.
|
||||
|
||||
O listener AgentOps é registrado no sistema de eventos do CrewAI via importação em `src/crewai/utilities/events/third_party/__init__.py`:
|
||||
|
||||
```python
|
||||
from .agentops_listener import agentops_listener
|
||||
```
|
||||
|
||||
Isso garante que o `agentops_listener` seja carregado quando o pacote `crewai.utilities.events` for importado.
|
||||
|
||||
## Uso Avançado: Handlers Escopados
|
||||
|
||||
Para lidar temporariamente com eventos (útil para testes ou operações específicas), você pode usar o context manager `scoped_handlers`:
|
||||
|
||||
```python
|
||||
from crewai.utilities.events import crewai_event_bus, CrewKickoffStartedEvent
|
||||
|
||||
with crewai_event_bus.scoped_handlers():
|
||||
@crewai_event_bus.on(CrewKickoffStartedEvent)
|
||||
def temp_handler(source, event):
|
||||
print("Este handler só existe neste contexto")
|
||||
|
||||
# Faça algo que emita eventos
|
||||
|
||||
# Fora do contexto, o handler temporário é removido
|
||||
```
|
||||
|
||||
## Casos de Uso
|
||||
|
||||
Listeners de evento podem ser usados para várias finalidades:
|
||||
|
||||
1. **Log e Monitoramento**: Monitore a execução do seu Crew e registre eventos importantes
|
||||
2. **Analytics**: Colete dados sobre o desempenho e comportamento do seu Crew
|
||||
3. **Depuração**: Configure listeners temporários para debugar problemas específicos
|
||||
4. **Integração**: Conecte o CrewAI a sistemas externos como plataformas de monitoramento, bancos de dados ou serviços de notificação
|
||||
5. **Comportamento Personalizado**: Dispare ações personalizadas com base em eventos específicos
|
||||
|
||||
## Boas Práticas
|
||||
|
||||
1. **Mantenha Handlers Leves**: Handlers de eventos devem ser leves e evitar operações bloqueantes
|
||||
2. **Tratamento de Erros**: Implemente tratamento de erros adequado nos event handlers para evitar que exceções afetem a execução principal
|
||||
3. **Limpeza**: Se seu listener alocar recursos, garanta o devido fechamento/liberação
|
||||
4. **Escuta Seletiva**: Escute apenas eventos que realmente precisa tratar
|
||||
5. **Testes**: Teste seus listeners de evento isoladamente para garantir que se comportam conforme esperado
|
||||
|
||||
Aproveitando o sistema de eventos do CrewAI, é possível estender a funcionalidade e integrá-lo facilmente à sua infraestrutura existente.
|
||||
509
docs/pt-BR/concepts/flows.mdx
Normal file
509
docs/pt-BR/concepts/flows.mdx
Normal file
@@ -0,0 +1,509 @@
|
||||
---
|
||||
title: Flows
|
||||
description: Saiba como criar e gerenciar fluxos de trabalho de IA usando CrewAI Flows.
|
||||
icon: arrow-progress
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O CrewAI Flows é um recurso poderoso projetado para simplificar a criação e o gerenciamento de fluxos de trabalho de IA. Os flows permitem que desenvolvedores combinem e coordenem tarefas de codificação e crews de forma eficiente, proporcionando uma estrutura robusta para a construção de automações de IA sofisticadas.
|
||||
|
||||
Os flows permitem que você crie fluxos de trabalho estruturados e orientados por eventos. Eles oferecem uma forma integrada de conectar múltiplas tarefas, gerenciar estado e controlar o fluxo de execução nas suas aplicações de IA. Com flows, você pode facilmente projetar e implementar processos de múltiplas etapas que exploram todo o potencial das capacidades do CrewAI.
|
||||
|
||||
1. **Criação Simplificada de Fluxos de Trabalho**: Conecte facilmente múltiplas crews e tarefas para criar workflows de IA complexos.
|
||||
|
||||
2. **Gerenciamento de Estado**: Flows facilitam muito o gerenciamento e o compartilhamento de estados entre diferentes tarefas do seu fluxo de trabalho.
|
||||
|
||||
3. **Arquitetura Orientada a Eventos**: Construído sobre um modelo orientado a eventos, permitindo fluxos dinâmicos e responsivos.
|
||||
|
||||
4. **Controle de Fluxo Flexível**: Implemente lógica condicional, loops e ramificações dentro dos seus fluxos.
|
||||
|
||||
## Primeiros Passos
|
||||
|
||||
Vamos criar um Flow simples no qual você usará a OpenAI para gerar uma cidade aleatória em uma tarefa e, em seguida, usará essa cidade para gerar uma curiosidade em outra tarefa.
|
||||
|
||||
```python Code
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
Na ilustração acima, criamos um Flow simples que gera uma cidade aleatória usando a OpenAI e depois cria uma curiosidade sobre essa cidade. O Flow consiste em duas tarefas: `generate_city` e `generate_fun_fact`. A tarefa `generate_city` é o ponto de início do Flow, enquanto a tarefa `generate_fun_fact` fica escutando o resultado da tarefa `generate_city`.
|
||||
|
||||
Cada instância de Flow recebe automaticamente um identificador único (UUID) em seu estado, que auxilia no rastreamento e gerenciamento das execuções. O estado também pode armazenar dados adicionais (como a cidade gerada e a curiosidade) que permanecem durante toda a execução do flow.
|
||||
|
||||
Ao executar o Flow, ele irá:
|
||||
1. Gerar um ID único para o estado do flow
|
||||
2. Gerar uma cidade aleatória e armazená-la no estado
|
||||
3. Gerar uma curiosidade sobre essa cidade e armazená-la no estado
|
||||
4. Imprimir os resultados no console
|
||||
|
||||
O ID único do estado e os dados armazenados podem ser úteis para rastrear execuções do flow e manter contexto entre as tarefas.
|
||||
|
||||
**Nota:** Certifique-se de configurar seu arquivo `.env` para armazenar sua `OPENAI_API_KEY`. Essa chave é necessária para autenticar as requisições à API da OpenAI.
|
||||
|
||||
### @start()
|
||||
|
||||
O decorador `@start()` é utilizado para marcar um método como ponto inicial de um Flow. Quando um Flow é iniciado, todos os métodos decorados com `@start()` são executados em paralelo. É possível ter múltiplos métodos start em um Flow, e todos eles serão executados quando o Flow iniciar.
|
||||
|
||||
### @listen()
|
||||
|
||||
O decorador `@listen()` é utilizado para marcar um método como ouvinte da saída de outra tarefa do Flow. O método decorado com `@listen()` será executado quando a tarefa especificada emitir uma saída. O método pode acessar a saída da tarefa à qual está escutando como argumento.
|
||||
|
||||
#### Utilização
|
||||
|
||||
O decorador `@listen()` pode ser usado de várias formas:
|
||||
|
||||
1. **Escutando um Método pelo Nome**: Você pode passar o nome do método ao qual deseja escutar como string. Quando esse método concluir, o método ouvinte será chamado.
|
||||
|
||||
```python Code
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
2. **Escutando um Método Diretamente**: Você pode passar o próprio método. Quando esse método concluir, o método ouvinte será chamado.
|
||||
```python Code
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
### Saída de um Flow
|
||||
|
||||
Acessar e manipular a saída de um Flow é essencial para integrar seus workflows de IA a aplicações ou sistemas maiores. O CrewAI Flows fornece mecanismos fáceis para recuperar a saída final, acessar resultados intermediários e gerenciar o estado geral do seu Flow.
|
||||
|
||||
#### Recuperando a Saída Final
|
||||
|
||||
Ao executar um Flow, a saída final é determinada pelo último método concluído. O método `kickoff()` retorna a saída desse método final.
|
||||
|
||||
Veja como acessar a saída final:
|
||||
|
||||
<CodeGroup>
|
||||
```python Code
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
```text Output
|
||||
---- Final Output ----
|
||||
Second method received: Output from first_method
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
|
||||
Neste exemplo, o `second_method` é o último método a ser concluído, logo sua saída será a saída final do Flow.
|
||||
O método `kickoff()` retorna essa saída, que é impressa no console. O método `plot()` irá gerar o arquivo HTML para visualizar o fluxo.
|
||||
|
||||
#### Acessando e Atualizando o Estado
|
||||
|
||||
Além de recuperar a saída final, você pode acessar e atualizar o estado dentro do seu Flow. O estado pode ser usado para armazenar e compartilhar dados entre diferentes métodos do Flow. Após a execução do Flow, você pode acessar o estado para recuperar informações adicionadas ou alteradas durante o processo.
|
||||
|
||||
Veja um exemplo de como atualizar e acessar o estado:
|
||||
|
||||
<CodeGroup>
|
||||
```python Code
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
```text Output
|
||||
Final Output: Hello from first_method - updated by second_method
|
||||
Final State:
|
||||
counter=2 message='Hello from first_method - updated by second_method'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
|
||||
|
||||
Neste exemplo, o estado é atualizado tanto por `first_method` quanto por `second_method`.
|
||||
Após o término da execução, é possível acessar o estado final e observar as atualizações realizadas por esses métodos.
|
||||
|
||||
Ao garantir que a saída do método final seja retornada e oferecer acesso ao estado, o CrewAI Flows facilita a integração dos resultados dos seus workflows de IA em aplicações maiores,
|
||||
além de permitir o gerenciamento e o acesso ao estado durante toda a execução do Flow.
|
||||
|
||||
## Gerenciamento de Estado em Flows
|
||||
|
||||
Gerenciar o estado de forma eficaz é fundamental para construir fluxos de trabalho de IA confiáveis e de fácil manutenção. O CrewAI Flows oferece mecanismos robustos para o gerenciamento de estado tanto não estruturado quanto estruturado,
|
||||
permitindo que o desenvolvedor escolha a abordagem que melhor se adapta à sua aplicação.
|
||||
|
||||
### Gerenciamento de Estado Não Estruturado
|
||||
|
||||
No gerenciamento de estado não estruturado, todo o estado é armazenado no atributo `state` da classe `Flow`.
|
||||
Essa abordagem oferece flexibilidade, permitindo que o desenvolvedor adicione ou modifique atributos do estado conforme necessário sem precisar definir um esquema rígido.
|
||||
Mesmo com estados não estruturados, os flows do CrewAI geram e mantêm automaticamente um identificador único (UUID) para cada instância de estado.
|
||||
|
||||
```python Code
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
|
||||
|
||||
**Nota:** O campo `id` é gerado e preservado automaticamente durante toda a execução do flow. Não é necessário gerenciá-lo ou defini-lo manualmente, e ele permanecerá mesmo ao atualizar o estado com novos dados.
|
||||
|
||||
**Pontos-Chave:**
|
||||
|
||||
- **Flexibilidade:** É possível adicionar atributos dinamicamente ao `self.state` sem restrições pré-definidas.
|
||||
- **Simplicidade:** Ideal para fluxos de trabalho diretos em que a estrutura do estado é mínima ou varia bastante.
|
||||
|
||||
### Gerenciamento de Estado Estruturado
|
||||
|
||||
No gerenciamento de estado estruturado, utilizam-se esquemas pré-definidos para garantir consistência e segurança de tipos em todo o workflow.
|
||||
Ao usar modelos como o `BaseModel` da Pydantic, os desenvolvedores podem definir a forma exata do estado, melhorando a validação e fornecendo auto-complete nos ambientes de desenvolvimento.
|
||||
|
||||
Cada estado nos flows do CrewAI recebe automaticamente um identificador único (UUID) para ajudar no rastreamento e gerenciamento. Esse ID é gerado e mantido automaticamente pelo sistema de flows.
|
||||
|
||||
```python Code
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
|
||||
|
||||
**Pontos-Chave:**
|
||||
|
||||
- **Esquema Definido:** `ExampleState` deixa claro a estrutura do estado, aumentando a legibilidade e a manutenção do código.
|
||||
- **Segurança de Tipos:** O uso da Pydantic garante que os atributos do estado tenham os tipos certos, reduzindo os erros em tempo de execução.
|
||||
- **Auto-Completar:** IDEs conseguem oferecer auto-completar e checagem de erros, graças ao modelo definido do estado.
|
||||
|
||||
### Escolhendo entre Estado Não Estruturado e Estruturado
|
||||
|
||||
- **Use Estado Não Estruturado quando:**
|
||||
- O estado do fluxo é simples ou altamente dinâmico.
|
||||
- Flexibilidade é mais importante do que uma definição rígida do estado.
|
||||
- Prototipagem rápida é necessária sem a sobrecarga de definição de esquemas.
|
||||
|
||||
- **Use Estado Estruturado quando:**
|
||||
- O flow exige uma estrutura de estado bem definida e consistente.
|
||||
- Segurança de tipos e validação são importantes para a confiabilidade da aplicação.
|
||||
- É desejado usar recursos da IDE como auto-completar e checagem de tipos para uma melhor experiência de desenvolvimento.
|
||||
|
||||
Ao oferecer as duas opções de gerenciamento de estado, o CrewAI Flows permite que desenvolvedores criem fluxos de IA que sejam ao mesmo tempo flexíveis e robustos, atendendo a uma ampla variedade de requisitos de aplicação.
|
||||
|
||||
## Persistência de Flow
|
||||
|
||||
O decorador @persist permite a persistência automática do estado nos flows do CrewAI, garantindo que você mantenha o estado do flow entre reinicializações ou execuções diferentes do workflow. Esse decorador pode ser aplicado tanto ao nível de classe, quanto ao nível de método, oferecendo flexibilidade sobre como gerenciar a persistência do estado.
|
||||
|
||||
### Persistência no Nível de Classe
|
||||
|
||||
Quando aplicado no nível da classe, o decorador @persist garante a persistência automática de todos os estados dos métodos do flow:
|
||||
|
||||
```python
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
### Persistência no Nível de Método
|
||||
|
||||
Para um controle mais granular, você pode aplicar @persist em métodos específicos:
|
||||
|
||||
```python
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
### Como Funciona
|
||||
|
||||
1. **Identificação Única do Estado**
|
||||
- Cada estado do flow recebe automaticamente um UUID único
|
||||
- O ID é preservado entre atualizações do estado e chamadas de métodos
|
||||
- Suporta tanto estados estruturados (Pydantic BaseModel) quanto não estruturados (dicionário)
|
||||
|
||||
2. **Backend SQLite Padrão**
|
||||
- O SQLiteFlowPersistence é o backend de armazenamento padrão
|
||||
- Os estados são salvos automaticamente em um banco de dados SQLite local
|
||||
- O tratamento de erros é robusto, oferecendo mensagens claras caso ocorram falhas nas operações de banco de dados
|
||||
|
||||
3. **Tratamento de Erros**
|
||||
- Mensagens de erro abrangentes para operações de banco de dados
|
||||
- Validação automática do estado ao salvar e carregar
|
||||
- Feedback claro quando houver problemas de persistência
|
||||
|
||||
### Considerações Importantes
|
||||
|
||||
- **Tipos de Estado**: São suportados tanto estados estruturados (Pydantic BaseModel) quanto não estruturados (dicionário)
|
||||
- **ID Automático**: O campo `id` é adicionado automaticamente se não estiver presente
|
||||
- **Recuperação de Estado**: Flows que falharem ou forem reiniciados podem recarregar automaticamente seu estado anterior
|
||||
- **Implementação Personalizada**: Você pode fornecer sua própria implementação de FlowPersistence para necessidades de armazenamento especializadas
|
||||
|
||||
### Vantagens Técnicas
|
||||
|
||||
1. **Controle Preciso Através de Acesso de Baixo Nível**
|
||||
- Acesso direto às operações de persistência para casos avançados
|
||||
- Controle detalhado via decoradores de persistência no nível do método
|
||||
- Inspeção de estado e recursos de depuração embutidos
|
||||
- Visibilidade total das mudanças e operações de persistência do estado
|
||||
|
||||
2. **Maior Confiabilidade**
|
||||
- Recuperação automática do estado após falhas no sistema ou reinicializações
|
||||
- Atualizações de estado baseadas em transações para garantir integridade dos dados
|
||||
- Mensagens de erro abrangentes e claras
|
||||
- Validação robusta durante operações de salvar e carregar estado
|
||||
|
||||
3. **Arquitetura Extensível**
|
||||
- Backend de persistência personalizável através da interface FlowPersistence
|
||||
- Suporte para soluções de armazenamento especializadas além do SQLite
|
||||
- Compatibilidade tanto com estados estruturados (Pydantic) quanto não estruturados (dict)
|
||||
- Integração perfeita com os padrões de flow existentes no CrewAI
|
||||
|
||||
A arquitetura de persistência enfatiza precisão técnica e opções de personalização, permitindo que desenvolvedores mantenham controle total sobre o gerenciamento de estado enquanto se beneficiam dos recursos de confiabilidade integrados.
|
||||
|
||||
## Controle de Flow
|
||||
|
||||
### Lógica Condicional: `or`
|
||||
|
||||
A função `or_` nos flows permite escutar múltiplos métodos e acionar o método ouvinte quando qualquer um dos métodos especificados gerar uma saída.
|
||||
|
||||
<CodeGroup>
|
||||
```python Code
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
```text Output
|
||||
Logger: Hello from the start method
|
||||
Logger: Hello from the second method
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
|
||||
|
||||
Ao executar esse Flow, o método `logger` será acionado pela saída tanto do `start_method` quanto do `second_method`.
|
||||
A função `or_` serve para escutar vários métodos e disparar o método ouvinte quando qualquer um emitir um resultado.
|
||||
|
||||
### Lógica Condicional: `and`
|
||||
|
||||
A função `and_` nos flows permite escutar múltiplos métodos e acionar o método ouvinte apenas quando todos os métodos especificados emitirem uma saída.
|
||||
|
||||
<CodeGroup>
|
||||
```python Code
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
```text Output
|
||||
---- Logger ----
|
||||
{'greeting': 'Hello from the start method', 'joke': 'What do computers eat? Microchips.'}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
|
||||
|
||||
Ao executar esse Flow, o método `logger` só será disparado quando ambos `start_method` e `second_method` emitirem uma saída.
|
||||
A função `and_` é usada para escutar vários métodos e acionar o método ouvinte apenas quando todas as condições forem atendidas.
|
||||
|
||||
### Router
|
||||
|
||||
O decorador `@router()` nos flows permite definir lógica de roteamento condicional baseada na saída de um método.
|
||||
Você pode especificar diferentes rotas conforme a saída do método, permitindo controlar o fluxo de execução de forma dinâmica.
|
||||
|
||||
<CodeGroup>
|
||||
```python Code
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
```text Output
|
||||
Starting the structured flow
|
||||
Third method running
|
||||
Fourth method running
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
|
||||
|
||||
No exemplo, o `start_method` gera um valor booleano aleatório e armazena no estado.
|
||||
O `second_method` usa o decorador `@router()` para decidir o roteamento conforme o valor booleano.
|
||||
Se o valor for `True`, retorna `"success"`, senão retorna `"failed"`.
|
||||
Os métodos `third_method` e `fourth_method` escutam a saída do `second_method` e executam com base no valor retornado.
|
||||
|
||||
Ao executar esse Flow, a saída será diferente dependendo do valor booleano aleatório gerado pelo `start_method`.
|
||||
|
||||
## Adicionando Agentes aos Flows
|
||||
|
||||
Os agentes podem ser integrados facilmente aos seus flows, oferecendo uma alternativa leve às crews completas quando você precisar executar tarefas simples e focadas. Veja um exemplo de como utilizar um agente em um flow para realizar uma pesquisa de mercado:
|
||||
|
||||
```python
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
|
||||
|
||||
Esse exemplo demonstra diversos recursos fundamentais do uso de agentes em flows:
|
||||
|
||||
1. **Saída Estruturada**: O uso de modelos Pydantic para definir o formato esperado da saída (`MarketAnalysis`) garante segurança de tipos e dados estruturados em todo o flow.
|
||||
|
||||
2. **Gerenciamento de Estado**: O estado do flow (`MarketResearchState`) mantém o contexto entre as etapas e armazena entradas e saídas.
|
||||
|
||||
3. **Integração de Ferramentas**: Os agentes podem usar ferramentas (como `WebsiteSearchTool`) para potencializar suas habilidades.
|
||||
|
||||
## Adicionando Crews aos Flows
|
||||
|
||||
Criar um flow com múltiplas crews no CrewAI é simples.
|
||||
|
||||
Você pode gerar um novo projeto CrewAI que já inclui toda a estrutura para criar um flow com várias crews executando o seguinte comando:
|
||||
|
||||
```bash
|
||||
crewai create flow name_of_flow
|
||||
```
|
||||
|
||||
Esse comando irá gerar um novo projeto CrewAI com a estrutura de pastas necessária. O projeto gerado inclui uma crew pré-criada chamada `poem_crew`, já funcional. Você pode usar essa crew como modelo, copiando, colando e editando para criar outras crews.
|
||||
|
||||
### Estrutura de Pastas
|
||||
|
||||
Após rodar o comando `crewai create flow name_of_flow`, você verá uma estrutura parecida com:
|
||||
|
||||
| Diretório/Arquivo | Descrição |
|
||||
| :------------------------ | :------------------------------------------------------------------- |
|
||||
| `name_of_flow/` | Diretório raiz do flow. |
|
||||
| ├── `crews/` | Contém diretórios para crews específicas. |
|
||||
| │ └── `poem_crew/` | Diretório da "poem_crew" com configurações e scripts. |
|
||||
| │ ├── `config/` | Arquivos de configuração da "poem_crew". |
|
||||
| │ │ ├── `agents.yaml` | YAML que define os agentes da "poem_crew". |
|
||||
| │ │ └── `tasks.yaml` | YAML que define as tarefas da "poem_crew". |
|
||||
| │ ├── `poem_crew.py` | Script da funcionalidade da "poem_crew". |
|
||||
| ├── `tools/` | Ferramentas adicionais usadas no flow. |
|
||||
| │ └── `custom_tool.py` | Implementação de ferramenta customizada. |
|
||||
| ├── `main.py` | Script principal do flow. |
|
||||
| ├── `README.md` | Descrição do projeto e instruções. |
|
||||
| ├── `pyproject.toml` | Arquivo de configurações e dependências do projeto. |
|
||||
| └── `.gitignore` | Arquivos e pastas a serem ignorados no controle de versão. |
|
||||
|
||||
### Construindo suas Crews
|
||||
|
||||
Na pasta `crews`, você pode definir múltiplas crews. Cada crew tem sua própria pasta, com arquivos de configuração e o arquivo de definição da crew. Por exemplo, a pasta `poem_crew` contém:
|
||||
|
||||
- `config/agents.yaml`: Define os agentes da crew.
|
||||
- `config/tasks.yaml`: Define as tarefas da crew.
|
||||
- `poem_crew.py`: Contém a definição da crew, incluindo agentes, tarefas, etc.
|
||||
|
||||
Você pode copiar, colar e editar a `poem_crew` para criar outras crews.
|
||||
|
||||
### Conectando Crews no `main.py`
|
||||
|
||||
No arquivo `main.py`, você cria seu flow e conecta as crews. É possível definir o fluxo usando a classe `Flow` e os decoradores `@start` e `@listen` para definir a ordem de execução.
|
||||
|
||||
Veja um exemplo de como conectar a `poem_crew` no arquivo `main.py`:
|
||||
|
||||
```python Code
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
Neste exemplo, a classe `PoemFlow` define um fluxo que gera a quantidade de frases, usa a `PoemCrew` para gerar um poema e, depois, salva o poema em um arquivo. O flow inicia com o método `kickoff()`, e o gráfico é gerado pelo método `plot()`.
|
||||
|
||||
|
||||
|
||||
### Executando o Flow
|
||||
|
||||
(Opcional) Antes de rodar o flow, instale as dependências executando:
|
||||
|
||||
```bash
|
||||
crewai install
|
||||
```
|
||||
|
||||
Após instalar as dependências, ative o ambiente virtual com:
|
||||
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
Com o ambiente ativado, execute o flow usando um dos comandos:
|
||||
|
||||
```bash
|
||||
crewai flow kickoff
|
||||
```
|
||||
|
||||
ou
|
||||
|
||||
```bash
|
||||
uv run kickoff
|
||||
```
|
||||
|
||||
O flow será executado, e você verá a saída no console.
|
||||
|
||||
## Plotando Flows
|
||||
|
||||
Visualizar seus fluxos de trabalho de IA proporciona insights valiosos sobre a estrutura e os caminhos de execução dos flows. O CrewAI oferece uma ferramenta de visualização poderosa que permite gerar plots interativos dos flows, facilitando o entendimento e a otimização dos workflows de IA.
|
||||
|
||||
### O que são Plots?
|
||||
|
||||
No CrewAI, plots são representações gráficas dos fluxos de trabalho de IA. Eles mostram as tarefas, suas conexões e o fluxo de dados entre elas. Essa visualização ajuda a compreender a sequência de operações, identificar gargalos e garantir que a lógica do workflow está alinhada com o esperado.
|
||||
|
||||
### Como Gerar um Plot
|
||||
|
||||
O CrewAI oferece duas formas práticas de gerar plots dos seus flows:
|
||||
|
||||
#### Opção 1: Usando o método `plot()`
|
||||
|
||||
Se estiver trabalhando diretamente com uma instância do flow, basta chamar o método `plot()` do objeto. Isso criará um arquivo HTML com o plot interativo do seu flow.
|
||||
|
||||
```python Code
|
||||
# (O código não é traduzido)
|
||||
```
|
||||
|
||||
Esse comando gera um arquivo chamado `my_flow_plot.html` no diretório atual. Abra esse arquivo em um navegador para visualizar o plot interativo.
|
||||
|
||||
#### Opção 2: Usando a Linha de Comando
|
||||
|
||||
Em projetos CrewAI estruturados, é possível gerar um plot pela linha de comando. Isso é útil para projetos maiores, onde você deseja visualizar toda a configuração do flow.
|
||||
|
||||
```bash
|
||||
crewai flow plot
|
||||
```
|
||||
|
||||
O comando gera um arquivo HTML com o plot do flow, semelhante ao método `plot()`. Basta abrir o arquivo no navegador para explorar o workflow.
|
||||
|
||||
### Entendendo o Plot
|
||||
|
||||
O plot gerado mostra nós representando as tarefas do seu flow, com setas indicando o fluxo de execução. A visualização é interativa, permitindo zoom, navegação e detalhes ao passar o mouse nos nós.
|
||||
|
||||
Ao visualizar seus flows, você tem clareza do formato do workflow, facilitando debug, otimização e comunicação dos seus processos de IA para outras pessoas.
|
||||
|
||||
### Conclusão
|
||||
|
||||
A plotagem dos flows é um recurso poderoso do CrewAI para aprimorar o design e o gerenciamento de fluxos de IA complexos. Usando o método `plot()` ou a linha de comando, você obtém uma visão visual dos workflows, benefício tanto para desenvolvimento quanto para apresentação.
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
Se você deseja explorar exemplos adicionais de flows, acompanhe alguns exemplos em nosso repositório de exemplos. Aqui estão quatro sugestões específicas de flows, cada uma demonstrando casos de uso distintos para você escolher conforme seu problema:
|
||||
|
||||
1. **Email Auto Responder Flow**: Este exemplo demonstra um loop infinito, onde um job de background roda continuamente automatizando respostas de email. É ideal para tarefas rotineiras sem intervenção manual. [Ver Exemplo](https://github.com/crewAIInc/crewAI-examples/tree/main/email_auto_responder_flow)
|
||||
|
||||
2. **Lead Score Flow**: Destaca como adicionar feedback humano e manipular diferentes ramos condicionais usando router. Um ótimo aprendizado para workflows com decisão dinâmica e supervisão humana. [Ver Exemplo](https://github.com/crewAIInc/crewAI-examples/tree/main/lead-score-flow)
|
||||
|
||||
3. **Write a Book Flow**: Exemplo ideal para encadear múltiplas crews, onde a saída de uma é usada por outra. Uma crew faz um sumário do livro inteiro, outra gera capítulos... Tudo conectado para entregar um livro completo. Perfeito para processos longos e coordenados. [Ver Exemplo](https://github.com/crewAIInc/crewAI-examples/tree/main/write_a_book_with_flows)
|
||||
|
||||
4. **Meeting Assistant Flow**: Demonstra como transmitir um evento para desencadear múltiplas ações posteriores. Exemplo: ao finalizar uma reunião, atualizar um Trello, enviar mensagem no Slack e salvar resultados ao mesmo tempo. Indicado para gerenciamento completo de tarefas e notificações. [Ver Exemplo](https://github.com/crewAIInc/crewAI-examples/tree/main/meeting_assistant_flow)
|
||||
|
||||
Explore esses exemplos para descobrir como aproveitar CrewAI Flows em diferentes contextos – desde automação de tarefas repetitivas até o gerenciamento de processos dinâmicos com decisões e feedback humano.
|
||||
|
||||
Além disso, confira nosso vídeo no YouTube sobre como utilizar flows no CrewAI abaixo!
|
||||
|
||||
<iframe
|
||||
width="560"
|
||||
height="315"
|
||||
src="https://www.youtube.com/embed/MTb5my6VOT8"
|
||||
title="YouTube video player"
|
||||
frameborder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
referrerpolicy="strict-origin-when-cross-origin"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
|
||||
## Executando Flows
|
||||
|
||||
Existem duas formas de executar um flow:
|
||||
|
||||
### Usando a API do Flow
|
||||
|
||||
Você pode executar um flow programaticamente criando uma instância da sua classe de flow e chamando o método `kickoff()`:
|
||||
|
||||
```python
|
||||
flow = ExampleFlow()
|
||||
result = flow.kickoff()
|
||||
```
|
||||
|
||||
### Usando a CLI
|
||||
|
||||
A partir da versão 0.103.0, é possível executar flows usando o comando `crewai run`:
|
||||
|
||||
```shell
|
||||
crewai run
|
||||
```
|
||||
|
||||
O comando detecta automaticamente se seu projeto é um flow (com base na configuração `type = "flow"` no pyproject.toml) e executa conforme o esperado. Esse é o método recomendado para executar flows pelo terminal.
|
||||
|
||||
Por compatibilidade retroativa, também é possível usar:
|
||||
|
||||
```shell
|
||||
crewai flow kickoff
|
||||
```
|
||||
|
||||
No entanto, o comando `crewai run` é agora o preferido, pois funciona tanto para crews quanto para flows.
|
||||
1059
docs/pt-BR/concepts/knowledge.mdx
Normal file
1059
docs/pt-BR/concepts/knowledge.mdx
Normal file
File diff suppressed because it is too large
Load Diff
884
docs/pt-BR/concepts/llms.mdx
Normal file
884
docs/pt-BR/concepts/llms.mdx
Normal file
@@ -0,0 +1,884 @@
|
||||
---
|
||||
title: 'LLMs'
|
||||
description: 'Um guia abrangente para configurar e usar Modelos de Linguagem de Grande Escala (LLMs) em seus projetos CrewAI'
|
||||
icon: 'microchip-ai'
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O CrewAI integra-se com múltiplos provedores de LLM através do LiteLLM, oferecendo flexibilidade para você escolher o modelo certo para o seu caso de uso específico. Este guia irá ajudá-lo a entender como configurar e usar diferentes provedores de LLM em seus projetos CrewAI.
|
||||
|
||||
## O que são LLMs?
|
||||
|
||||
Modelos de Linguagem de Grande Escala (LLMs) são a inteligência central por trás dos agentes CrewAI. Eles permitem que os agentes compreendam o contexto, tomem decisões e gerem respostas semelhantes às humanas. Veja o que você precisa saber:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Noções Básicas de LLM" icon="brain">
|
||||
Modelos de Linguagem de Grande Escala são sistemas de IA treinados em grandes volumes de dados textuais. Eles potencializam a inteligência dos agentes CrewAI, permitindo compreender e gerar textos de voz humana.
|
||||
</Card>
|
||||
<Card title="Janela de Contexto" icon="window">
|
||||
A janela de contexto determina quanto texto um LLM pode processar de uma só vez. Janelas maiores (por exemplo, 128K tokens) permitem mais contexto, porém podem ser mais caras e lentas.
|
||||
</Card>
|
||||
<Card title="Temperatura" icon="temperature-three-quarters">
|
||||
A temperatura (0.0 a 1.0) controla a aleatoriedade das respostas. Valores mais baixos (ex.: 0.2) produzem respostas mais focadas e determinísticas, enquanto valores mais altos (ex.: 0.8) aumentam criatividade e variabilidade.
|
||||
</Card>
|
||||
<Card title="Seleção de Provedor" icon="server">
|
||||
Cada provedor de LLM (ex.: OpenAI, Anthropic, Google) oferece modelos diferentes, com capacidades, preços e recursos variados. Escolha conforme suas necessidades de precisão, velocidade e custo.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Configurando seu LLM
|
||||
|
||||
Existem diferentes locais no código do CrewAI onde você pode especificar o modelo a ser utilizado. Após definir o modelo usado, será necessário fornecer a configuração (como uma chave de API) para cada provedor de modelo. Veja a seção de [exemplos de configuração de provedores](#provider-configuration-examples) para seu provedor.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="1. Variáveis de Ambiente">
|
||||
A maneira mais simples de começar. Defina o modelo diretamente em seu ambiente, usando um arquivo `.env` ou no código do seu aplicativo. Se você utilizou `crewai create` para iniciar seu projeto, já estará configurado.
|
||||
|
||||
```bash .env
|
||||
MODEL=model-id # e.g. gpt-4o, gemini-2.0-flash, claude-3-sonnet-...
|
||||
|
||||
# Lembre-se de definir suas chaves de API aqui também. Veja a seção
|
||||
# do Provedor abaixo.
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Nunca envie chaves de API para controle de versão. Use arquivos de ambiente (.env) ou o gerenciamento de segredos do seu sistema.
|
||||
</Warning>
|
||||
</Tab>
|
||||
<Tab title="2. Configuração YAML">
|
||||
Crie um arquivo YAML para definir as configurações dos seus agentes. Este método é ótimo para controle de versão e colaboração em equipe:
|
||||
|
||||
```yaml agents.yaml {6}
|
||||
researcher:
|
||||
role: Research Specialist
|
||||
goal: Conduct comprehensive research and analysis
|
||||
backstory: A dedicated research professional with years of experience
|
||||
verbose: true
|
||||
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
|
||||
# (veja exemplos de configuração de provedores abaixo para mais)
|
||||
```
|
||||
|
||||
<Info>
|
||||
A configuração YAML permite:
|
||||
- Controlar versões das configurações dos agentes
|
||||
- Trocar facilmente entre diferentes modelos
|
||||
- Compartilhar configurações entre membros da equipe
|
||||
- Documentar escolhas de modelos e seus propósitos
|
||||
</Info>
|
||||
</Tab>
|
||||
<Tab title="3. Código Direto">
|
||||
Para máxima flexibilidade, configure os LLMs diretamente no seu código Python:
|
||||
|
||||
```python {4,8}
|
||||
from crewai import LLM
|
||||
|
||||
# Configuração básica
|
||||
llm = LLM(model="model-id-here") # gpt-4o, gemini-2.0-flash, anthropic/claude...
|
||||
|
||||
# Configuração avançada com parâmetros detalhados
|
||||
llm = LLM(
|
||||
model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude...
|
||||
temperature=0.7, # Mais alto para saídas criativas
|
||||
timeout=120, # Segundos para aguardar resposta
|
||||
max_tokens=4000, # Comprimento máximo da resposta
|
||||
top_p=0.9, # Parâmetro de amostragem nucleus
|
||||
frequency_penalty=0.1 , # Reduz repetição
|
||||
presence_penalty=0.1, # Incentiva diversidade de tópicos
|
||||
response_format={"type": "json"}, # Para respostas estruturadas
|
||||
seed=42 # Para resultados reproduzíveis
|
||||
)
|
||||
```
|
||||
|
||||
<Info>
|
||||
Explicações dos parâmetros:
|
||||
- `temperature`: Controla a aleatoriedade (0.0-1.0)
|
||||
- `timeout`: Tempo máximo de espera pela resposta
|
||||
- `max_tokens`: Limita o comprimento da resposta
|
||||
- `top_p`: Alternativa à temperatura para amostragem
|
||||
- `frequency_penalty`: Reduz repetição de palavras
|
||||
- `presence_penalty`: Incentiva novos tópicos
|
||||
- `response_format`: Especifica formato de saída
|
||||
- `seed`: Garante resultados consistentes
|
||||
</Info>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Exemplos de Configuração de Provedores
|
||||
|
||||
O CrewAI suporta uma grande variedade de provedores de LLM, cada um com recursos, métodos de autenticação e capacidades de modelo únicos.
|
||||
Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, configurar e otimizar o LLM que melhor atende às necessidades do seu projeto.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="OpenAI">
|
||||
Defina as seguintes variáveis de ambiente no seu arquivo `.env`:
|
||||
|
||||
```toml Code
|
||||
# Obrigatório
|
||||
OPENAI_API_KEY=sk-...
|
||||
|
||||
# Opcional
|
||||
OPENAI_API_BASE=<custom-base-url>
|
||||
OPENAI_ORGANIZATION=<your-org-id>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
from crewai import LLM
|
||||
|
||||
llm = LLM(
|
||||
model="openai/gpt-4", # chamar modelo por provider/model_name
|
||||
temperature=0.8,
|
||||
max_tokens=150,
|
||||
top_p=0.9,
|
||||
frequency_penalty=0.1,
|
||||
presence_penalty=0.1,
|
||||
stop=["END"],
|
||||
seed=42
|
||||
)
|
||||
```
|
||||
|
||||
OpenAI é um dos líderes em modelos LLM com uma ampla gama de modelos e recursos.
|
||||
|
||||
| Modelo | Janela de Contexto | Melhor Para |
|
||||
|----------------------|---------------------|------------------------------------------|
|
||||
| GPT-4 | 8.192 tokens | Tarefas de alta precisão, raciocínio complexo |
|
||||
| GPT-4 Turbo | 128.000 tokens | Conteúdo longo, análise de documentos |
|
||||
| GPT-4o & GPT-4o-mini | 128.000 tokens | Processamento de contexto amplo com bom custo-benefício |
|
||||
| o3-mini | 200.000 tokens | Raciocínio rápido, tarefas complexas |
|
||||
| o1-mini | 128.000 tokens | Raciocínio rápido, tarefas complexas |
|
||||
| o1-preview | 128.000 tokens | Raciocínio rápido, tarefas complexas |
|
||||
| o1 | 200.000 tokens | Raciocínio rápido, tarefas complexas |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Meta-Llama">
|
||||
A API Llama da Meta fornece acesso à família de modelos de linguagem de grande escala da Meta.
|
||||
A API está disponível através da [Meta Llama API](https://llama.developer.meta.com?utm_source=partner-crewai&utm_medium=website).
|
||||
Defina as seguintes variáveis de ambiente no seu arquivo `.env`:
|
||||
|
||||
```toml Code
|
||||
# Configuração chave da API Meta Llama
|
||||
LLAMA_API_KEY=LLM|your_api_key_here
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
from crewai import LLM
|
||||
|
||||
# Inicializar Meta Llama LLM
|
||||
llm = LLM(
|
||||
model="meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8",
|
||||
temperature=0.8,
|
||||
stop=["END"],
|
||||
seed=42
|
||||
)
|
||||
```
|
||||
|
||||
Todos os modelos listados em https://llama.developer.meta.com/docs/models/ são suportados.
|
||||
|
||||
| ID do Modelo | Comprimento contexto entrada | Comprimento contexto saída | Modalidades de entrada | Modalidades de saída |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8` | 128k | 4028 | Texto, Imagem | Texto |
|
||||
| `meta_llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 128k | 4028 | Texto, Imagem | Texto |
|
||||
| `meta_llama/Llama-3.3-70B-Instruct` | 128k | 4028 | Texto | Texto |
|
||||
| `meta_llama/Llama-3.3-8B-Instruct` | 128k | 4028 | Texto | Texto |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Anthropic">
|
||||
```toml Code
|
||||
# Obrigatório
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
|
||||
# Opcional
|
||||
ANTHROPIC_API_BASE=<custom-base-url>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="anthropic/claude-3-sonnet-20240229-v1:0",
|
||||
temperature=0.7
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Google (Gemini API)">
|
||||
Defina sua chave de API no seu arquivo `.env`. Se precisar de uma chave, ou encontrar uma existente, verifique o [AI Studio](https://aistudio.google.com/apikey).
|
||||
|
||||
```toml .env
|
||||
# https://ai.google.dev/gemini-api/docs/api-key
|
||||
GEMINI_API_KEY=<your-api-key>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
from crewai import LLM
|
||||
|
||||
llm = LLM(
|
||||
model="gemini/gemini-2.0-flash",
|
||||
temperature=0.7,
|
||||
)
|
||||
```
|
||||
|
||||
### Modelos Gemini
|
||||
|
||||
O Google oferece uma variedade de modelos poderosos otimizados para diferentes casos de uso.
|
||||
|
||||
| Modelo | Janela de Contexto | Melhor Para |
|
||||
|----------------------------------|--------------------|---------------------------------------------------------------------|
|
||||
| gemini-2.5-flash-preview-04-17 | 1M tokens | Pensamento adaptativo, eficiência de custo |
|
||||
| gemini-2.5-pro-preview-05-06 | 1M tokens | Pensamento e raciocínio avançados, compreensão multimodal, codificação avançada, etc. |
|
||||
| gemini-2.0-flash | 1M tokens | Próxima geração de recursos, velocidade, raciocínio e streaming em tempo real |
|
||||
| gemini-2.0-flash-lite | 1M tokens | Eficiência de custo e baixa latência |
|
||||
| gemini-1.5-flash | 1M tokens | Modelo multimodal equilibrado, bom para maioria das tarefas |
|
||||
| gemini-1.5-flash-8B | 1M tokens | Mais rápido, mais eficiente em custo, adequado para tarefas de alta frequência |
|
||||
| gemini-1.5-pro | 2M tokens | Melhor desempenho para uma ampla variedade de tarefas de raciocínio, incluindo lógica, codificação e colaboração criativa |
|
||||
|
||||
A lista completa de modelos está disponível na [documentação dos modelos Gemini](https://ai.google.dev/gemini-api/docs/models).
|
||||
|
||||
### Gemma
|
||||
|
||||
A API Gemini também permite uso de sua chave de API para acessar [modelos Gemma](https://ai.google.dev/gemma/docs) hospedados na infraestrutura Google.
|
||||
|
||||
| Modelo | Janela de Contexto |
|
||||
|----------------|-------------------|
|
||||
| gemma-3-1b-it | 32k tokens |
|
||||
| gemma-3-4b-it | 32k tokens |
|
||||
| gemma-3-12b-it | 32k tokens |
|
||||
| gemma-3-27b-it | 128k tokens |
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Google (Vertex AI)">
|
||||
Obtenha as credenciais pelo Google Cloud Console, salve em um arquivo JSON e carregue com o código a seguir:
|
||||
```python Code
|
||||
import json
|
||||
|
||||
file_path = 'path/to/vertex_ai_service_account.json'
|
||||
|
||||
# Carregar o arquivo JSON
|
||||
with open(file_path, 'r') as file:
|
||||
vertex_credentials = json.load(file)
|
||||
|
||||
# Converter credenciais em string JSON
|
||||
vertex_credentials_json = json.dumps(vertex_credentials)
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
from crewai import LLM
|
||||
|
||||
llm = LLM(
|
||||
model="gemini/gemini-1.5-pro-latest",
|
||||
temperature=0.7,
|
||||
vertex_credentials=vertex_credentials_json
|
||||
)
|
||||
```
|
||||
|
||||
O Google oferece uma variedade de modelos poderosos otimizados para diferentes casos de uso:
|
||||
|
||||
| Modelo | Janela de Contexto | Melhor Para |
|
||||
|----------------------------------|--------------------|---------------------------------------------------------------------|
|
||||
| gemini-2.5-flash-preview-04-17 | 1M tokens | Pensamento adaptativo, eficiência de custo |
|
||||
| gemini-2.5-pro-preview-05-06 | 1M tokens | Pensamento e raciocínio avançados, compreensão multimodal, codificação avançada, etc. |
|
||||
| gemini-2.0-flash | 1M tokens | Próxima geração de recursos, velocidade, raciocínio e streaming em tempo real |
|
||||
| gemini-2.0-flash-lite | 1M tokens | Eficiência de custo e baixa latência |
|
||||
| gemini-1.5-flash | 1M tokens | Modelo multimodal equilibrado, bom para maioria das tarefas |
|
||||
| gemini-1.5-flash-8B | 1M tokens | Mais rápido, mais eficiente em custo, adequado para tarefas de alta frequência |
|
||||
| gemini-1.5-pro | 2M tokens | Melhor desempenho para uma ampla variedade de tarefas de raciocínio, incluindo lógica, codificação e colaboração criativa |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Azure">
|
||||
```toml Code
|
||||
# Obrigatório
|
||||
AZURE_API_KEY=<your-api-key>
|
||||
AZURE_API_BASE=<your-resource-url>
|
||||
AZURE_API_VERSION=<api-version>
|
||||
|
||||
# Opcional
|
||||
AZURE_AD_TOKEN=<your-azure-ad-token>
|
||||
AZURE_API_TYPE=<your-azure-api-type>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="azure/gpt-4",
|
||||
api_version="2023-05-15"
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="AWS Bedrock">
|
||||
```toml Code
|
||||
AWS_ACCESS_KEY_ID=<your-access-key>
|
||||
AWS_SECRET_ACCESS_KEY=<your-secret-key>
|
||||
AWS_DEFAULT_REGION=<your-region>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="bedrock/anthropic.claude-3-sonnet-20240229-v1:0"
|
||||
)
|
||||
```
|
||||
|
||||
Antes de usar o Amazon Bedrock, certifique-se de ter o boto3 instalado em seu ambiente
|
||||
|
||||
[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) é um serviço gerenciado que fornece acesso a múltiplos modelos fundamentais dos principais provedores de IA através de uma API unificada, permitindo o desenvolvimento seguro e responsável de aplicações de IA.
|
||||
|
||||
| Modelo | Janela de Contexto | Melhor Para |
|
||||
|--------------------------|------------------------|---------------------------------------------------------------------|
|
||||
| Amazon Nova Pro | Até 300k tokens | Alto desempenho, equilíbrio entre precisão, velocidade e custo em tarefas diversas. |
|
||||
| Amazon Nova Micro | Até 128k tokens | Modelo texto-only de alta performance, custo-benefício, otimizado para baixa latência. |
|
||||
| Amazon Nova Lite | Até 300k tokens | Alto desempenho, processamento multimodal acessível para texto, imagem, vídeo em tempo real. |
|
||||
| Claude 3.7 Sonnet | Até 128k tokens | Alto desempenho para raciocínio complexo, programação & agentes de IA|
|
||||
| Claude 3.5 Sonnet v2 | Até 200k tokens | Modelo avançado especializado em engenharia de software, capacidades agenticas e interação computacional com custo otimizado. |
|
||||
| Claude 3.5 Sonnet | Até 200k tokens | Alto desempenho com inteligência e raciocínio excepcionais, equilíbrio entre velocidade-custo. |
|
||||
| Claude 3.5 Haiku | Até 200k tokens | Modelo multimodal rápido e compacto, otimizado para respostas rápidas e interações humanas naturais |
|
||||
| Claude 3 Sonnet | Até 200k tokens | Modelo multimodal equilibrando inteligência e velocidade para grandes volumes de uso. |
|
||||
| Claude 3 Haiku | Até 200k tokens | Compacto, multimodal, otimizado para respostas rápidas e diálogo natural |
|
||||
| Claude 3 Opus | Até 200k tokens | Modelo multimodal mais avançado para tarefas complexas com raciocínio humano e entendimento contextual superior. |
|
||||
| Claude 2.1 | Até 200k tokens | Versão aprimorada com janela de contexto aumentada, maior confiabilidade, menos alucinações para aplicações longas e RAG |
|
||||
| Claude | Até 100k tokens | Modelo versátil para diálogos sofisticados, conteúdo criativo e instruções precisas. |
|
||||
| Claude Instant | Até 100k tokens | Modelo rápido e de baixo custo para tarefas diárias, como diálogos, análise, sumarização e Q&A em documentos |
|
||||
| Llama 3.1 405B Instruct | Até 128k tokens | LLM avançado para geração de dados sintéticos, distilação e inferência para chatbots, programação, tarefas de domínio específico. |
|
||||
| Llama 3.1 70B Instruct | Até 128k tokens | Potencializa conversas complexas com entendimento contextual superior, raciocínio e geração de texto. |
|
||||
| Llama 3.1 8B Instruct | Até 128k tokens | Modelo de última geração, entendimento de linguagem, raciocínio e geração de texto. |
|
||||
| Llama 3 70B Instruct | Até 8k tokens | Potencializa conversas complexas com entendimento contextual superior, raciocínio e geração de texto. |
|
||||
| Llama 3 8B Instruct | Até 8k tokens | LLM de última geração com excelente desempenho em linguagem e geração de texto. |
|
||||
| Titan Text G1 - Lite | Até 4k tokens | Modelo leve e econômico para tarefas em inglês e ajuste fino, focado em sumarização e geração de conteúdo. |
|
||||
| Titan Text G1 - Express | Até 8k tokens | Modelo versátil para tarefas gerais de linguagem, chat e aplicações RAG com suporte a inglês e 100+ línguas. |
|
||||
| Cohere Command | Até 4k tokens | Modelo especializado em seguir comandos do usuário e entregar soluções empresariais práticas. |
|
||||
| Jurassic-2 Mid | Até 8.191 tokens | Modelo econômico equilibrando qualidade e custo para tarefas como Q&A, sumarização e geração de conteúdo. |
|
||||
| Jurassic-2 Ultra | Até 8.191 tokens | Geração avançada de texto e compreensão, excelente em análise e criação de conteúdo complexo. |
|
||||
| Jamba-Instruct | Até 256k tokens | Modelo com janela de contexto extendida para geração de texto, sumarização e Q&A de baixo custo. |
|
||||
| Mistral 7B Instruct | Até 32k tokens | LLM atende instruções, solicitações e gera texto criativo. |
|
||||
| Mistral 8x7B Instruct | Até 32k tokens | MOE LLM que atende instruções, solicitações e gera texto criativo. |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Amazon SageMaker">
|
||||
```toml Code
|
||||
AWS_ACCESS_KEY_ID=<your-access-key>
|
||||
AWS_SECRET_ACCESS_KEY=<your-secret-key>
|
||||
AWS_DEFAULT_REGION=<your-region>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="sagemaker/<my-endpoint>"
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Mistral">
|
||||
Defina as seguintes variáveis de ambiente no seu arquivo `.env`:
|
||||
```toml Code
|
||||
MISTRAL_API_KEY=<your-api-key>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="mistral/mistral-large-latest",
|
||||
temperature=0.7
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Nvidia NIM">
|
||||
Defina as seguintes variáveis de ambiente no seu arquivo `.env`:
|
||||
```toml Code
|
||||
NVIDIA_API_KEY=<your-api-key>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="nvidia_nim/meta/llama3-70b-instruct",
|
||||
temperature=0.7
|
||||
)
|
||||
```
|
||||
|
||||
O Nvidia NIM oferece uma suíte abrangente de modelos para diversos usos, desde tarefas gerais até aplicações especializadas.
|
||||
|
||||
| Modelo | Janela de Contexto | Melhor Para |
|
||||
|--------------------------------------------------------------------------|--------------------|---------------------------------------------------------------------|
|
||||
| nvidia/mistral-nemo-minitron-8b-8k-instruct | 8.192 tokens | Modelo pequeno de linguagem topo de linha para chatbots, assistentes virtuais e geração de conteúdo. |
|
||||
| nvidia/nemotron-4-mini-hindi-4b-instruct | 4.096 tokens | SLM bilíngue Hindi-Inglês para inferência no dispositivo, específico para língua hindi. |
|
||||
| nvidia/llama-3.1-nemotron-70b-instruct | 128k tokens | Personalizado para respostas mais úteis |
|
||||
| nvidia/llama3-chatqa-1.5-8b | 128k tokens | LLM avançado para respostas contextuais de alta qualidade em chatbots e mecanismos de busca. |
|
||||
| nvidia/llama3-chatqa-1.5-70b | 128k tokens | LLM avançado para respostas contextuais de alta qualidade para chatbots e mecanismos de busca. |
|
||||
| nvidia/vila | 128k tokens | Modelo multmodal visão-linguagem para compreensão de texto/img/vídeo com respostas informativas |
|
||||
| nvidia/neva-22 | 4.096 tokens | Modelo de visão-linguagem multimodal para compreensão textos/imagens e respostas informativas |
|
||||
| nvidia/nemotron-mini-4b-instruct | 8.192 tokens | Tarefas gerais |
|
||||
| nvidia/usdcode-llama3-70b-instruct | 128k tokens | LLM de ponta para queries OpenUSD e geração de código USD-Python. |
|
||||
| nvidia/nemotron-4-340b-instruct | 4.096 tokens | Gera dados sintéticos diversos simulando características reais. |
|
||||
| meta/codellama-70b | 100k tokens | LLM capaz de gerar código a partir de linguagem natural e vice-versa.|
|
||||
| meta/llama2-70b | 4.096 tokens | Modelo de IA avançado para geração de textos e códigos. |
|
||||
| meta/llama3-8b-instruct | 8.192 tokens | LLM de última geração, entendimento de linguagem, raciocínio e geração de texto. |
|
||||
| meta/llama3-70b-instruct | 8.192 tokens | Potencializa conversas complexas com entendimento contextual superior, raciocínio e geração de texto.|
|
||||
| meta/llama-3.1-8b-instruct | 128k tokens | Modelo compacto de última geração, com compreensão, raciocínio e geração de texto superior. |
|
||||
| meta/llama-3.1-70b-instruct | 128k tokens | Potencializa conversas complexas com entendimento contextual superior, raciocínio e geração de texto. |
|
||||
| meta/llama-3.1-405b-instruct | 128k tokens | LLM avançado para geração sintética de dados, destilação e inferência para chatbots, código, tarefas de domínio específico. |
|
||||
| meta/llama-3.2-1b-instruct | 128k tokens | Pequeno modelo de linguagem de última geração, entendimento, raciocínio e geração textual.|
|
||||
| meta/llama-3.2-3b-instruct | 128k tokens | Pequeno modelo de linguagem de última geração, entendimento, raciocínio e geração textual.|
|
||||
| meta/llama-3.2-11b-vision-instruct | 128k tokens | Pequeno modelo de linguagem de última geração, entendimento, raciocínio e geração textual multimodal.|
|
||||
| meta/llama-3.2-90b-vision-instruct | 128k tokens | Pequeno modelo de linguagem de última geração, entendimento, raciocínio e geração textual multimodal.|
|
||||
| google/gemma-7b | 8.192 tokens | Modelo avançado de geração de texto, compreensão, transformação e programação.|
|
||||
| google/gemma-2b | 8.192 tokens | Modelo avançado de geração de texto, compreensão, transformação e programação.|
|
||||
| google/codegemma-7b | 8.192 tokens | Modelo avançado baseado no Gemma-7B do Google, especializado em geração de códigos e autocomplete.|
|
||||
| google/codegemma-1.1-7b | 8.192 tokens | Modelo avançado para geração, complemento, raciocínio e instrução em código.|
|
||||
| google/recurrentgemma-2b | 8.192 tokens | Modelo baseado em arquitetura recorrente para inferência mais rápida em sequências longas.|
|
||||
| google/gemma-2-9b-it | 8.192 tokens | Modelo avançado de geração de texto, compreensão, transformação e programação.|
|
||||
| google/gemma-2-27b-it | 8.192 tokens | Modelo avançado de geração de texto, compreensão, transformação e programação.|
|
||||
| google/gemma-2-2b-it | 8.192 tokens | Modelo avançado de geração de texto, compreensão, transformação e programação.|
|
||||
| google/deplot | 512 tokens | Modelo visual por linguagem para entender gráficos e converter em tabelas.|
|
||||
| google/paligemma | 8.192 tokens | Modelo visão-linguagem experto em compreender texto e visual, gerando respostas informativas.|
|
||||
| mistralai/mistral-7b-instruct-v0.2 | 32k tokens | LLM que segue instruções, completa pedidos e gera texto criativo. |
|
||||
| mistralai/mixtral-8x7b-instruct-v0.1 | 8.192 tokens | MOE LLM para seguir instruções e gerar versões criativas de texto. |
|
||||
| mistralai/mistral-large | 4.096 tokens | Geração de dados sintéticos. |
|
||||
| mistralai/mixtral-8x22b-instruct-v0.1 | 8.192 tokens | Geração de dados sintéticos. |
|
||||
| mistralai/mistral-7b-instruct-v0.3 | 32k tokens | LLM que segue instruções, completa pedidos e gera texto criativo. |
|
||||
| nv-mistralai/mistral-nemo-12b-instruct | 128k tokens | Modelo de linguagem avançado para raciocínio, código, tarefas multilíngues; roda em uma única GPU.|
|
||||
| mistralai/mamba-codestral-7b-v0.1 | 256k tokens | Modelo para escrita e interação com código em múltiplas linguagens e tarefas.|
|
||||
| microsoft/phi-3-mini-128k-instruct | 128K tokens | LLM leve, de última geração, com habilidades de lógica e matemática.|
|
||||
| microsoft/phi-3-mini-4k-instruct | 4.096 tokens | LLM leve, de última geração, com habilidades de lógica e matemática.|
|
||||
| microsoft/phi-3-small-8k-instruct | 8.192 tokens | LLM leve, de última geração, com habilidades de lógica e matemática.|
|
||||
| microsoft/phi-3-small-128k-instruct | 128K tokens | LLM leve, de última geração, com habilidades de lógica e matemática.|
|
||||
| microsoft/phi-3-medium-4k-instruct | 4.096 tokens | LLM leve, de última geração, com habilidades de lógica e matemática.|
|
||||
| microsoft/phi-3-medium-128k-instruct | 128K tokens | LLM leve, de última geração, com habilidades de lógica e matemática.|
|
||||
| microsoft/phi-3.5-mini-instruct | 128K tokens | LLM multilíngue leve para aplicações de IA restritas em memória e tempo.|
|
||||
| microsoft/phi-3.5-moe-instruct | 128K tokens | LLM avançada baseada em Mixture of Experts para geração eficiente de conteúdo.|
|
||||
| microsoft/kosmos-2 | 1.024 tokens | Modelo multimodal revolucionário para compreender e raciocinar elementos visuais em imagens.|
|
||||
| microsoft/phi-3-vision-128k-instruct | 128k tokens | Modelo multimodal aberto de ponta para raciocínio de alta qualidade a partir de imagens.|
|
||||
| microsoft/phi-3.5-vision-instruct | 128k tokens | Modelo multimodal aberto de ponta para raciocínio de alta qualidade a partir de imagens.|
|
||||
| databricks/dbrx-instruct | 12k tokens | LLM de uso geral com desempenho no estado da arte para linguagem, programação e RAG.|
|
||||
| snowflake/arctic | 1.024 tokens | Inferência eficiente para aplicações empresariais focadas em SQL e programação.|
|
||||
| aisingapore/sea-lion-7b-instruct | 4.096 tokens | LLM para representação e diversidade linguística e cultural do sudeste asiático.|
|
||||
| ibm/granite-8b-code-instruct | 4.096 tokens | LLM para programação: geração, explicação e diálogo multi-turn de código.|
|
||||
| ibm/granite-34b-code-instruct | 8.192 tokens | LLM para programação: geração, explicação e diálogo multi-turn de código.|
|
||||
| ibm/granite-3.0-8b-instruct | 4.096 tokens | Pequeno modelo avançado, com suporte a RAG, sumário, classificação, código e IA agentica.|
|
||||
| ibm/granite-3.0-3b-a800m-instruct | 4.096 tokens | Modelo Mixture of Experts eficiente para RAG, sumário, extração de entidades, classificação.|
|
||||
| mediatek/breeze-7b-instruct | 4.096 tokens | Gera dados sintéticos diversos.|
|
||||
| upstage/solar-10.7b-instruct | 4.096 tokens | Excelente em tarefas de PLN, especialmente seguir instruções, raciocínio e matemática.|
|
||||
| writer/palmyra-med-70b-32k | 32k tokens | LLM líder para respostas médicas precisas e contextuais.|
|
||||
| writer/palmyra-med-70b | 32k tokens | LLM líder para respostas médicas precisas e contextuais.|
|
||||
| writer/palmyra-fin-70b-32k | 32k tokens | LLM especializada em análise financeira, relatórios e processamento de dados.|
|
||||
| 01-ai/yi-large | 32k tokens | Poderoso para inglês e chinês, incluindo chatbot e escrita criativa.|
|
||||
| deepseek-ai/deepseek-coder-6.7b-instruct | 2k tokens | Modelo avançado para geração de código, autocomplete, infilling.|
|
||||
| rakuten/rakutenai-7b-instruct | 1.024 tokens | LLM topo de linha, compreensão, raciocínio e geração textual.|
|
||||
| rakuten/rakutenai-7b-chat | 1.024 tokens | LLM topo de linha, compreensão, raciocínio e geração textual.|
|
||||
| baichuan-inc/baichuan2-13b-chat | 4.096 tokens | Suporte a chat em chinês/inglês, programação, matemática, seguir instruções, resolver quizzes.|
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Local NVIDIA NIM Deployed using WSL2">
|
||||
|
||||
O NVIDIA NIM permite rodar LLMs potentes localmente em máquinas Windows usando WSL2 (Windows Subsystem for Linux).
|
||||
Este método aproveita o GPU NVIDIA para inferência privativa, segura e econômica, sem depender de serviços em nuvem.
|
||||
Perfeito para desenvolvimento, testes ou produção onde privacidade ou funcionalidades offline são necessárias.
|
||||
|
||||
Aqui está um guia passo a passo para configurar um modelo local NVIDIA NIM:
|
||||
|
||||
1. Siga as instruções de instalação no [site da NVIDIA](https://docs.nvidia.com/nim/wsl2/latest/getting-started.html)
|
||||
|
||||
2. Instale o modelo local. Para Llama 3.1-8b siga as [instruções](https://build.nvidia.com/meta/llama-3_1-8b-instruct/deploy)
|
||||
|
||||
3. Configure seus modelos locais crewai:
|
||||
|
||||
```python Code
|
||||
from crewai.llm import LLM
|
||||
|
||||
local_nvidia_nim_llm = LLM(
|
||||
model="openai/meta/llama-3.1-8b-instruct", # é compatível com openai-api
|
||||
base_url="http://localhost:8000/v1",
|
||||
api_key="<your_api_key|any text if you have not configured it>", # api_key obrigatório, pode usar qualquer texto
|
||||
)
|
||||
|
||||
# Então pode usá-lo no seu crew:
|
||||
|
||||
@CrewBase
|
||||
class MyCrew():
|
||||
# ...
|
||||
|
||||
@agent
|
||||
def researcher(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['researcher'], # type: ignore[index]
|
||||
llm=local_nvidia_nim_llm
|
||||
)
|
||||
|
||||
# ...
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Groq">
|
||||
Defina as seguintes variáveis de ambiente no seu arquivo `.env`:
|
||||
|
||||
```toml Code
|
||||
GROQ_API_KEY=<your-api-key>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="groq/llama-3.2-90b-text-preview",
|
||||
temperature=0.7
|
||||
)
|
||||
```
|
||||
| Modelo | Janela de Contexto | Melhor Para |
|
||||
|-------------------|---------------------|------------------------------------------|
|
||||
| Llama 3.1 70B/8B | 131.072 tokens | Alta performance e tarefas de contexto grande|
|
||||
| Llama 3.2 Série | 8.192 tokens | Tarefas gerais |
|
||||
| Mixtral 8x7B | 32.768 tokens | Equilíbrio entre performance e contexto |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="IBM watsonx.ai">
|
||||
Defina as seguintes variáveis de ambiente no seu arquivo `.env`:
|
||||
```toml Code
|
||||
# Obrigatório
|
||||
WATSONX_URL=<your-url>
|
||||
WATSONX_APIKEY=<your-apikey>
|
||||
WATSONX_PROJECT_ID=<your-project-id>
|
||||
|
||||
# Opcional
|
||||
WATSONX_TOKEN=<your-token>
|
||||
WATSONX_DEPLOYMENT_SPACE_ID=<your-space-id>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="watsonx/meta-llama/llama-3-1-70b-instruct",
|
||||
base_url="https://api.watsonx.ai/v1"
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ollama (LLMs Locais)">
|
||||
1. Instale o Ollama: [ollama.ai](https://ollama.ai/)
|
||||
2. Rode um modelo: `ollama run llama3`
|
||||
3. Configure:
|
||||
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="ollama/llama3:70b",
|
||||
base_url="http://localhost:11434"
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Fireworks AI">
|
||||
Defina as seguintes variáveis de ambiente no seu arquivo `.env`:
|
||||
```toml Code
|
||||
FIREWORKS_API_KEY=<your-api-key>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="fireworks_ai/accounts/fireworks/models/llama-v3-70b-instruct",
|
||||
temperature=0.7
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Perplexity AI">
|
||||
Defina as seguintes variáveis de ambiente no seu arquivo `.env`:
|
||||
```toml Code
|
||||
PERPLEXITY_API_KEY=<your-api-key>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="llama-3.1-sonar-large-128k-online",
|
||||
base_url="https://api.perplexity.ai/"
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Hugging Face">
|
||||
Defina as seguintes variáveis de ambiente no seu arquivo `.env`:
|
||||
```toml Code
|
||||
HF_TOKEN=<your-api-key>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="huggingface/meta-llama/Meta-Llama-3.1-8B-Instruct"
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="SambaNova">
|
||||
Defina as seguintes variáveis de ambiente no seu arquivo `.env`:
|
||||
|
||||
```toml Code
|
||||
SAMBANOVA_API_KEY=<your-api-key>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="sambanova/Meta-Llama-3.1-8B-Instruct",
|
||||
temperature=0.7
|
||||
)
|
||||
```
|
||||
| Modelo | Janela de Contexto | Melhor Para |
|
||||
|-------------------|---------------------------|----------------------------------------------|
|
||||
| Llama 3.1 70B/8B | Até 131.072 tokens | Alto desempenho, tarefas com grande contexto |
|
||||
| Llama 3.1 405B | 8.192 tokens | Desempenho e qualidade de saída elevada |
|
||||
| Llama 3.2 Série | 8.192 tokens | Tarefas gerais e multimodais |
|
||||
| Llama 3.3 70B | Até 131.072 tokens | Desempenho e qualidade de saída elevada |
|
||||
| Família Qwen2 | 8.192 tokens | Desempenho e qualidade de saída elevada |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Cerebras">
|
||||
Defina as seguintes variáveis de ambiente no seu arquivo `.env`:
|
||||
```toml Code
|
||||
# Obrigatório
|
||||
CEREBRAS_API_KEY=<your-api-key>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="cerebras/llama3.1-70b",
|
||||
temperature=0.7,
|
||||
max_tokens=8192
|
||||
)
|
||||
```
|
||||
|
||||
<Info>
|
||||
Recursos do Cerebras:
|
||||
- Altas velocidades de inferência
|
||||
- Preços competitivos
|
||||
- Equilíbrio entre velocidade e qualidade
|
||||
- Suporte a longas janelas de contexto
|
||||
</Info>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Open Router">
|
||||
Defina as seguintes variáveis de ambiente no seu arquivo `.env`:
|
||||
```toml Code
|
||||
OPENROUTER_API_KEY=<your-api-key>
|
||||
```
|
||||
|
||||
Exemplo de uso em seu projeto CrewAI:
|
||||
```python Code
|
||||
llm = LLM(
|
||||
model="openrouter/deepseek/deepseek-r1",
|
||||
base_url="https://openrouter.ai/api/v1",
|
||||
api_key=OPENROUTER_API_KEY
|
||||
)
|
||||
```
|
||||
|
||||
<Info>
|
||||
Modelos do Open Router:
|
||||
- openrouter/deepseek/deepseek-r1
|
||||
- openrouter/deepseek/deepseek-chat
|
||||
</Info>
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Respostas em streaming
|
||||
|
||||
O CrewAI suporta respostas em streaming de LLMs, permitindo que sua aplicação receba e processe saídas em tempo real assim que são geradas.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Configuração Básica">
|
||||
Ative o streaming definindo o parâmetro `stream` como `True` ao inicializar seu LLM:
|
||||
|
||||
```python
|
||||
from crewai import LLM
|
||||
|
||||
# Crie um LLM com streaming ativado
|
||||
llm = LLM(
|
||||
model="openai/gpt-4o",
|
||||
stream=True # Ativar streaming
|
||||
)
|
||||
```
|
||||
|
||||
Quando o streaming está ativado, as respostas são entregues em partes à medida que vão sendo geradas, criando uma experiência mais responsiva para o usuário.
|
||||
</Tab>
|
||||
|
||||
<Tab title="Manipulação de Eventos">
|
||||
O CrewAI emite eventos para cada chunk recebido durante o streaming:
|
||||
|
||||
```python
|
||||
from crewai.utilities.events import (
|
||||
LLMStreamChunkEvent
|
||||
)
|
||||
from crewai.utilities.events.base_event_listener import BaseEventListener
|
||||
|
||||
class MyCustomListener(BaseEventListener):
|
||||
def setup_listeners(self, crewai_event_bus):
|
||||
@crewai_event_bus.on(LLMStreamChunkEvent)
|
||||
def on_llm_stream_chunk(self, event: LLMStreamChunkEvent):
|
||||
# Clique para cada chunk assim que chegar
|
||||
print(f"Received chunk: {event.chunk}")
|
||||
|
||||
my_listener = MyCustomListener()
|
||||
```
|
||||
|
||||
<Tip>
|
||||
[Clique aqui](https://docs.crewai.com/concepts/event-listener#event-listeners) para mais detalhes
|
||||
</Tip>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Chamada Estruturada de LLM
|
||||
|
||||
O CrewAI suporta respostas estruturadas de LLMs permitindo que você defina um `response_format` usando um modelo Pydantic. Isso permite que o framework automaticamente faça o parsing e valide a saída, facilitando a integração da resposta em sua aplicação sem pós-processamento manual.
|
||||
|
||||
Por exemplo, é possível definir um modelo Pydantic para representar a resposta esperada e passá-lo como `response_format` ao instanciar o LLM. O modelo será utilizado para converter a resposta do LLM em um objeto Python estruturado.
|
||||
|
||||
```python Code
|
||||
from crewai import LLM
|
||||
|
||||
class Dog(BaseModel):
|
||||
name: str
|
||||
age: int
|
||||
breed: str
|
||||
|
||||
|
||||
llm = LLM(model="gpt-4o", response_format=Dog)
|
||||
|
||||
response = llm.call(
|
||||
"Analyze the following messages and return the name, age, and breed. "
|
||||
"Meet Kona! She is 3 years old and is a black german shepherd."
|
||||
)
|
||||
print(response)
|
||||
|
||||
# Output:
|
||||
# Dog(name='Kona', age=3, breed='black german shepherd')
|
||||
```
|
||||
|
||||
## Recursos Avançados e Otimização
|
||||
|
||||
Saiba como obter o máximo da configuração do seu LLM:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Gestão da Janela de Contexto">
|
||||
O CrewAI inclui recursos inteligentes para gerenciamento de contexto:
|
||||
|
||||
```python
|
||||
from crewai import LLM
|
||||
|
||||
# O CrewAI automaticamente gerencia:
|
||||
# 1. Contagem e acompanhamento de tokens
|
||||
# 2. Resumo de conteúdo quando necessário
|
||||
# 3. Divisão de tarefas para grandes contextos
|
||||
|
||||
llm = LLM(
|
||||
model="gpt-4",
|
||||
max_tokens=4000, # Limitar tamanho da resposta
|
||||
)
|
||||
```
|
||||
|
||||
<Info>
|
||||
Boas práticas para o gerenciamento de contexto:
|
||||
1. Prefira modelos com janelas apropriadas
|
||||
2. Pré-processe entradas muito longas
|
||||
3. Utilize divisão para documentos grandes
|
||||
4. Monitore tokens para otimizar custos
|
||||
</Info>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Otimização de Performance">
|
||||
<Steps>
|
||||
<Step title="Otimização do Uso de Tokens">
|
||||
Escolha a janela de contexto certa para sua tarefa:
|
||||
- Tarefas pequenas (até 4K tokens): Modelos padrão
|
||||
- Tarefas médias (entre 4K-32K): Modelos aprimorados
|
||||
- Tarefas grandes (acima de 32K): Modelos com contexto expandido
|
||||
|
||||
```python
|
||||
# Configure o modelo com as opções certas
|
||||
llm = LLM(
|
||||
model="openai/gpt-4-turbo-preview",
|
||||
temperature=0.7, # Ajuste conforme a tarefa
|
||||
max_tokens=4096, # Defina conforme a necessidade da saída
|
||||
timeout=300 # Timeout maior para tarefas complexas
|
||||
)
|
||||
```
|
||||
<Tip>
|
||||
- Temperaturas baixas (0.1 a 0.3) para respostas factuais
|
||||
- Temperaturas altas (0.7 a 0.9) para tarefas criativas
|
||||
</Tip>
|
||||
</Step>
|
||||
|
||||
<Step title="Boas Práticas">
|
||||
1. Monitore o uso de tokens
|
||||
2. Implemente limites de taxa (rate limiting)
|
||||
3. Use cache quando possível
|
||||
4. Defina limites apropriados para max_tokens
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Info>
|
||||
Lembre-se de monitorar regularmente o uso de tokens e ajustar suas configurações para otimizar custos e desempenho.
|
||||
</Info>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Descartar Parâmetros Adicionais">
|
||||
O CrewAI usa Litellm internamente para chamadas LLM, permitindo descartar parâmetros adicionais desnecessários para seu caso de uso. Isso pode simplificar seu código e reduzir a complexidade da configuração do LLM.
|
||||
Por exemplo, se não precisar enviar o parâmetro <code>stop</code>, basta omiti-lo na chamada do LLM:
|
||||
|
||||
```python
|
||||
from crewai import LLM
|
||||
import os
|
||||
|
||||
os.environ["OPENAI_API_KEY"] = "<api-key>"
|
||||
|
||||
o3_llm = LLM(
|
||||
model="o3",
|
||||
drop_params=True,
|
||||
additional_drop_params=["stop"]
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Problemas Comuns e Soluções
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Autenticação">
|
||||
<Warning>
|
||||
A maioria dos problemas de autenticação pode ser resolvida verificando o formato da chave da API e os nomes das variáveis de ambiente.
|
||||
</Warning>
|
||||
|
||||
```bash
|
||||
# OpenAI
|
||||
OPENAI_API_KEY=sk-...
|
||||
|
||||
# Anthropic
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Nomes dos Modelos">
|
||||
<Check>
|
||||
Sempre inclua o prefixo do provedor nos nomes dos modelos
|
||||
</Check>
|
||||
|
||||
```python
|
||||
# Correto
|
||||
llm = LLM(model="openai/gpt-4")
|
||||
|
||||
# Incorreto
|
||||
llm = LLM(model="gpt-4")
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Comprimento do Contexto">
|
||||
<Tip>
|
||||
Use modelos de contexto expandido para tarefas extensas
|
||||
</Tip>
|
||||
|
||||
```python
|
||||
# Modelo com contexto expandido
|
||||
llm = LLM(model="openai/gpt-4o") # 128K tokens
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
992
docs/pt-BR/concepts/memory.mdx
Normal file
992
docs/pt-BR/concepts/memory.mdx
Normal file
@@ -0,0 +1,992 @@
|
||||
---
|
||||
title: Memória
|
||||
description: Aproveitando sistemas de memória no framework CrewAI para aprimorar as capacidades dos agentes.
|
||||
icon: database
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O framework CrewAI oferece um sistema de memória sofisticado projetado para aprimorar significativamente as capacidades dos agentes de IA. O CrewAI disponibiliza **três abordagens distintas de memória** que atendem a diferentes casos de uso:
|
||||
|
||||
1. **Sistema Básico de Memória** - Memória de curto prazo, longo prazo e de entidades integradas
|
||||
2. **Memória de Usuário** - Memória específica do usuário com integração ao Mem0 (abordagem legada)
|
||||
3. **Memória Externa** - Provedores de memória externos autônomos (nova abordagem)
|
||||
|
||||
## Componentes do Sistema de Memória
|
||||
|
||||
| Componente | Descrição |
|
||||
| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Memória de Curto Prazo** | Armazena temporariamente interações e resultados recentes usando `RAG`, permitindo que os agentes recordem e utilizem informações relevantes ao contexto atual durante as execuções. |
|
||||
| **Memória de Longo Prazo** | Preserva informações valiosas e aprendizados de execuções passadas, permitindo que os agentes construam e refinem seu conhecimento ao longo do tempo. |
|
||||
| **Memória de Entidades** | Captura e organiza informações sobre entidades (pessoas, lugares, conceitos) encontradas durante tarefas, facilitando um entendimento mais profundo e o mapeamento de relacionamentos. Utiliza `RAG` para armazenar informações de entidades. |
|
||||
| **Memória Contextual** | Mantém o contexto das interações combinando `ShortTermMemory`, `LongTermMemory` e `EntityMemory`, auxiliando na coerência e relevância das respostas dos agentes ao longo de uma sequência de tarefas ou conversas. |
|
||||
|
||||
## 1. Sistema Básico de Memória (Recomendado)
|
||||
|
||||
A abordagem mais simples e comum de uso. Ative a memória para sua crew com um único parâmetro:
|
||||
|
||||
### Início Rápido
|
||||
```python
|
||||
from crewai import Crew, Agent, Task, Process
|
||||
|
||||
# Habilitar o sistema básico de memória
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
process=Process.sequential,
|
||||
memory=True, # Ativa memória de curto prazo, longo prazo e de entidades
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
### Como Funciona
|
||||
- **Memória de Curto Prazo**: Usa ChromaDB com RAG para o contexto atual
|
||||
- **Memória de Longo Prazo**: Usa SQLite3 para armazenar resultados de tarefas entre sessões
|
||||
- **Memória de Entidades**: Usa RAG para rastrear entidades (pessoas, lugares, conceitos)
|
||||
- **Local de Armazenamento**: Localidade específica da plataforma via pacote `appdirs`
|
||||
- **Diretório de Armazenamento Personalizado**: Defina a variável de ambiente `CREWAI_STORAGE_DIR`
|
||||
|
||||
## Transparência no Local de Armazenamento
|
||||
|
||||
<Info>
|
||||
**Compreendendo os Locais de Armazenamento**: CrewAI utiliza diretórios específicos da plataforma para guardar arquivos de memória e conhecimento seguindo as convenções do sistema operacional. Conhecer esses locais ajuda na implantação em produção, backups e depuração.
|
||||
</Info>
|
||||
|
||||
### Onde o CrewAI Armazena os Arquivos
|
||||
|
||||
Por padrão, o CrewAI usa a biblioteca `appdirs` para determinar os locais de armazenamento conforme a convenção da plataforma. Veja exatamente onde seus arquivos são armazenados:
|
||||
|
||||
#### Locais de Armazenamento Padrão por Plataforma
|
||||
|
||||
**macOS:**
|
||||
```
|
||||
~/Library/Application Support/CrewAI/{project_name}/
|
||||
├── knowledge/ # Arquivos base de conhecimento ChromaDB
|
||||
├── short_term_memory/ # Arquivos de memória de curto prazo ChromaDB
|
||||
├── long_term_memory/ # Arquivos de memória de longo prazo ChromaDB
|
||||
├── entities/ # Arquivos de memória de entidades ChromaDB
|
||||
└── long_term_memory_storage.db # Banco de dados SQLite
|
||||
```
|
||||
|
||||
**Linux:**
|
||||
```
|
||||
~/.local/share/CrewAI/{project_name}/
|
||||
├── knowledge/
|
||||
├── short_term_memory/
|
||||
├── long_term_memory/
|
||||
├── entities/
|
||||
└── long_term_memory_storage.db
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```
|
||||
C:\Users\{username}\AppData\Local\CrewAI\{project_name}\
|
||||
├── knowledge\
|
||||
├── short_term_memory\
|
||||
├── long_term_memory\
|
||||
├── entities\
|
||||
└── long_term_memory_storage.db
|
||||
```
|
||||
|
||||
### Encontrando Seu Local de Armazenamento
|
||||
|
||||
Para ver exatamente onde o CrewAI está armazenando arquivos em seu sistema:
|
||||
|
||||
```python
|
||||
from crewai.utilities.paths import db_storage_path
|
||||
import os
|
||||
|
||||
# Obter o caminho base de armazenamento
|
||||
storage_path = db_storage_path()
|
||||
print(f"CrewAI storage location: {storage_path}")
|
||||
|
||||
# Listar todos os diretórios e arquivos do CrewAI
|
||||
if os.path.exists(storage_path):
|
||||
print("\nStored files and directories:")
|
||||
for item in os.listdir(storage_path):
|
||||
item_path = os.path.join(storage_path, item)
|
||||
if os.path.isdir(item_path):
|
||||
print(f"📁 {item}/")
|
||||
# Exibir coleções ChromaDB
|
||||
if os.path.exists(item_path):
|
||||
for subitem in os.listdir(item_path):
|
||||
print(f" └── {subitem}")
|
||||
else:
|
||||
print(f"📄 {item}")
|
||||
else:
|
||||
print("No CrewAI storage directory found yet.")
|
||||
```
|
||||
|
||||
### Controlando Locais de Armazenamento
|
||||
|
||||
#### Opção 1: Variável de Ambiente (Recomendado)
|
||||
```python
|
||||
import os
|
||||
from crewai import Crew
|
||||
|
||||
# Definir local de armazenamento personalizado
|
||||
os.environ["CREWAI_STORAGE_DIR"] = "./my_project_storage"
|
||||
|
||||
# Toda a memória e conhecimento serão salvos em ./my_project_storage/
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
memory=True
|
||||
)
|
||||
```
|
||||
|
||||
#### Opção 2: Caminho de Armazenamento Personalizado
|
||||
```python
|
||||
import os
|
||||
from crewai import Crew
|
||||
from crewai.memory import LongTermMemory
|
||||
from crewai.memory.storage.ltm_sqlite_storage import LTMSQLiteStorage
|
||||
|
||||
# Configurar local de armazenamento personalizado
|
||||
custom_storage_path = "./storage"
|
||||
os.makedirs(custom_storage_path, exist_ok=True)
|
||||
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
long_term_memory=LongTermMemory(
|
||||
storage=LTMSQLiteStorage(
|
||||
db_path=f"{custom_storage_path}/memory.db"
|
||||
)
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
#### Opção 3: Armazenamento Específico de Projeto
|
||||
```python
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
# Armazenar no diretório do projeto
|
||||
project_root = Path(__file__).parent
|
||||
storage_dir = project_root / "crewai_storage"
|
||||
|
||||
os.environ["CREWAI_STORAGE_DIR"] = str(storage_dir)
|
||||
|
||||
# Todo o armazenamento ficará agora na pasta do projeto
|
||||
```
|
||||
|
||||
### Padrão do Provedor de Embedding
|
||||
|
||||
<Info>
|
||||
**Provedor de Embedding Padrão**: O CrewAI utiliza embeddings do OpenAI por padrão para garantir consistência e confiabilidade. Você pode facilmente customizar para combinar com seu provedor LLM ou utilizar embeddings locais.
|
||||
</Info>
|
||||
|
||||
#### Compreendendo o Comportamento Padrão
|
||||
```python
|
||||
# Ao utilizar Claude como seu LLM...
|
||||
from crewai import Agent, LLM
|
||||
|
||||
agent = Agent(
|
||||
role="Analyst",
|
||||
goal="Analyze data",
|
||||
backstory="Expert analyst",
|
||||
llm=LLM(provider="anthropic", model="claude-3-sonnet") # Usando Claude
|
||||
)
|
||||
|
||||
# O CrewAI usará embeddings OpenAI por padrão para garantir consistência
|
||||
# Você pode customizar facilmente para combinar com seu provedor preferido
|
||||
```
|
||||
|
||||
#### Personalizando Provedores de Embedding
|
||||
```python
|
||||
from crewai import Crew
|
||||
|
||||
# Opção 1: Combinar com seu provedor de LLM
|
||||
crew = Crew(
|
||||
agents=[agent],
|
||||
tasks=[task],
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "anthropic", # Combine com seu provedor de LLM
|
||||
"config": {
|
||||
"api_key": "your-anthropic-key",
|
||||
"model": "text-embedding-3-small"
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
# Opção 2: Use embeddings locais (sem chamadas para API externa)
|
||||
crew = Crew(
|
||||
agents=[agent],
|
||||
tasks=[task],
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "ollama",
|
||||
"config": {"model": "mxbai-embed-large"}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Depuração de Problemas de Armazenamento
|
||||
|
||||
#### Verifique Permissões do Armazenamento
|
||||
```python
|
||||
import os
|
||||
from crewai.utilities.paths import db_storage_path
|
||||
|
||||
storage_path = db_storage_path()
|
||||
print(f"Storage path: {storage_path}")
|
||||
print(f"Path exists: {os.path.exists(storage_path)}")
|
||||
print(f"Is writable: {os.access(storage_path, os.W_OK) if os.path.exists(storage_path) else 'Path does not exist'}")
|
||||
|
||||
# Crie com permissões apropriadas
|
||||
if not os.path.exists(storage_path):
|
||||
os.makedirs(storage_path, mode=0o755, exist_ok=True)
|
||||
print(f"Created storage directory: {storage_path}")
|
||||
```
|
||||
|
||||
#### Inspecione Coleções do ChromaDB
|
||||
```python
|
||||
import chromadb
|
||||
from crewai.utilities.paths import db_storage_path
|
||||
|
||||
# Conecte-se ao ChromaDB do CrewAI
|
||||
storage_path = db_storage_path()
|
||||
chroma_path = os.path.join(storage_path, "knowledge")
|
||||
|
||||
if os.path.exists(chroma_path):
|
||||
client = chromadb.PersistentClient(path=chroma_path)
|
||||
collections = client.list_collections()
|
||||
|
||||
print("ChromaDB Collections:")
|
||||
for collection in collections:
|
||||
print(f" - {collection.name}: {collection.count()} documentos")
|
||||
else:
|
||||
print("No ChromaDB storage found")
|
||||
```
|
||||
|
||||
#### Resetar Armazenamento (Depuração)
|
||||
```python
|
||||
from crewai import Crew
|
||||
|
||||
# Limpar todo o armazenamento de memória
|
||||
crew = Crew(agents=[...], tasks=[...], memory=True)
|
||||
|
||||
# Limpar tipos específicos de memória
|
||||
crew.reset_memories(command_type='short') # Memória de curto prazo
|
||||
crew.reset_memories(command_type='long') # Memória de longo prazo
|
||||
crew.reset_memories(command_type='entity') # Memória de entidades
|
||||
crew.reset_memories(command_type='knowledge') # Armazenamento de conhecimento
|
||||
```
|
||||
|
||||
### Melhores Práticas para Produção
|
||||
|
||||
1. **Defina o `CREWAI_STORAGE_DIR`** para um local conhecido em produção para maior controle
|
||||
2. **Escolha explicitamente provedores de embeddings** para coincidir com seu setup de LLM
|
||||
3. **Monitore o tamanho do diretório de armazenamento** em casos de grande escala
|
||||
4. **Inclua diretórios de armazenamento** em sua política de backup
|
||||
5. **Defina permissões apropriadas de arquivo** (0o755 para diretórios, 0o644 para arquivos)
|
||||
6. **Use caminhos relativos ao projeto** para implantações containerizadas
|
||||
|
||||
### Problemas Comuns de Armazenamento
|
||||
|
||||
**Erros "ChromaDB permission denied":**
|
||||
```bash
|
||||
# Corrija permissões
|
||||
chmod -R 755 ~/.local/share/CrewAI/
|
||||
```
|
||||
|
||||
**Erros "Database is locked":**
|
||||
```python
|
||||
# Certifique-se que apenas uma instância CrewAI acesse o armazenamento
|
||||
import fcntl
|
||||
import os
|
||||
|
||||
storage_path = db_storage_path()
|
||||
lock_file = os.path.join(storage_path, ".crewai.lock")
|
||||
|
||||
with open(lock_file, 'w') as f:
|
||||
fcntl.flock(f.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
|
||||
# Seu código CrewAI aqui
|
||||
```
|
||||
|
||||
**Armazenamento não persiste entre execuções:**
|
||||
```python
|
||||
# Verifique se o local do armazenamento é consistente
|
||||
import os
|
||||
print("CREWAI_STORAGE_DIR:", os.getenv("CREWAI_STORAGE_DIR"))
|
||||
print("Current working directory:", os.getcwd())
|
||||
print("Computed storage path:", db_storage_path())
|
||||
```
|
||||
|
||||
## Configuração Personalizada de Embedders
|
||||
|
||||
O CrewAI suporta múltiplos provedores de embeddings para oferecer flexibilidade na escolha da melhor opção para seu caso de uso. Aqui está um guia completo para configuração de diferentes provedores de embeddings para seu sistema de memória.
|
||||
|
||||
### Por que Escolher Diferentes Provedores de Embeddings?
|
||||
|
||||
- **Otimização de Custos**: Embeddings locais (Ollama) são gratuitos após configuração inicial
|
||||
- **Privacidade**: Mantenha seus dados locais com Ollama ou use seu provedor preferido na nuvem
|
||||
- **Desempenho**: Alguns modelos têm melhor desempenho para domínios ou idiomas específicos
|
||||
- **Consistência**: Combine seu provedor de embedding com o de LLM
|
||||
- **Conformidade**: Atenda a requisitos regulatórios ou organizacionais
|
||||
|
||||
### OpenAI Embeddings (Padrão)
|
||||
|
||||
A OpenAI oferece embeddings confiáveis e de alta qualidade para a maioria dos cenários.
|
||||
|
||||
```python
|
||||
from crewai import Crew
|
||||
|
||||
# Configuração básica OpenAI (usa a variável de ambiente OPENAI_API_KEY)
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model": "text-embedding-3-small" # ou "text-embedding-3-large"
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
# Configuração avançada OpenAI
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"api_key": "your-openai-api-key", # Opcional: sobrescreve variável de ambiente
|
||||
"model": "text-embedding-3-large",
|
||||
"dimensions": 1536, # Opcional: reduz as dimensões para armazenamento menor
|
||||
"organization_id": "your-org-id" # Opcional: para contas organizacionais
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Azure OpenAI Embeddings
|
||||
|
||||
Para empresas que utilizam deploys Azure OpenAI.
|
||||
|
||||
```python
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "openai", # Use openai como provider para Azure
|
||||
"config": {
|
||||
"api_key": "your-azure-api-key",
|
||||
"api_base": "https://your-resource.openai.azure.com/",
|
||||
"api_type": "azure",
|
||||
"api_version": "2023-05-15",
|
||||
"model": "text-embedding-3-small",
|
||||
"deployment_id": "your-deployment-name" # Nome do deploy Azure
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Google AI Embeddings
|
||||
|
||||
Use modelos de embeddings de texto do Google para integração com serviços do Google Cloud.
|
||||
|
||||
```python
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "google",
|
||||
"config": {
|
||||
"api_key": "your-google-api-key",
|
||||
"model": "text-embedding-004" # ou "text-embedding-preview-0409"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Vertex AI Embeddings
|
||||
|
||||
Para usuários do Google Cloud com acesso ao Vertex AI.
|
||||
|
||||
```python
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "vertexai",
|
||||
"config": {
|
||||
"project_id": "your-gcp-project-id",
|
||||
"region": "us-central1", # ou sua região preferencial
|
||||
"api_key": "your-service-account-key",
|
||||
"model_name": "textembedding-gecko"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Ollama Embeddings (Local)
|
||||
|
||||
Execute embeddings localmente para privacidade e economia.
|
||||
|
||||
```python
|
||||
# Primeiro, instale e rode Ollama localmente, depois baixe um modelo de embedding:
|
||||
# ollama pull mxbai-embed-large
|
||||
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "ollama",
|
||||
"config": {
|
||||
"model": "mxbai-embed-large", # ou "nomic-embed-text"
|
||||
"url": "http://localhost:11434/api/embeddings" # URL padrão do Ollama
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
# Para instalações personalizadas do Ollama
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "ollama",
|
||||
"config": {
|
||||
"model": "mxbai-embed-large",
|
||||
"url": "http://your-ollama-server:11434/api/embeddings"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Cohere Embeddings
|
||||
|
||||
Utilize os modelos de embedding da Cohere para suporte multilíngue.
|
||||
|
||||
```python
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "cohere",
|
||||
"config": {
|
||||
"api_key": "your-cohere-api-key",
|
||||
"model": "embed-english-v3.0" # ou "embed-multilingual-v3.0"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### VoyageAI Embeddings
|
||||
|
||||
Embeddings de alto desempenho otimizados para tarefas de recuperação.
|
||||
|
||||
```python
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "voyageai",
|
||||
"config": {
|
||||
"api_key": "your-voyage-api-key",
|
||||
"model": "voyage-large-2", # ou "voyage-code-2" para código
|
||||
"input_type": "document" # ou "query"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### AWS Bedrock Embeddings
|
||||
|
||||
Para usuários AWS com acesso ao Bedrock.
|
||||
|
||||
```python
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "bedrock",
|
||||
"config": {
|
||||
"aws_access_key_id": "your-access-key",
|
||||
"aws_secret_access_key": "your-secret-key",
|
||||
"region_name": "us-east-1",
|
||||
"model": "amazon.titan-embed-text-v1"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Hugging Face Embeddings
|
||||
|
||||
Utilize modelos open-source do Hugging Face.
|
||||
|
||||
```python
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "huggingface",
|
||||
"config": {
|
||||
"api_key": "your-hf-token", # Opcional para modelos públicos
|
||||
"model": "sentence-transformers/all-MiniLM-L6-v2",
|
||||
"api_url": "https://api-inference.huggingface.co" # ou seu endpoint customizado
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### IBM Watson Embeddings
|
||||
|
||||
Para usuários do IBM Cloud.
|
||||
|
||||
```python
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "watson",
|
||||
"config": {
|
||||
"api_key": "your-watson-api-key",
|
||||
"url": "your-watson-instance-url",
|
||||
"model": "ibm/slate-125m-english-rtrvr"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Como Escolher o Provedor de Embedding Certo
|
||||
|
||||
| Provedor | Melhor Para | Prós | Contras |
|
||||
|:---------|:----------|:------|:------|
|
||||
| **OpenAI** | Uso geral, confiabilidade | Alta qualidade, bem testado | Custo, requer chave de API |
|
||||
| **Ollama** | Privacidade, economia | Gratuito, local, privado | Requer configuração local |
|
||||
| **Google AI** | Ecossistema Google | Bom desempenho | Requer conta Google |
|
||||
| **Azure OpenAI** | Empresas, conformidade | Recursos corporativos | Configuração mais complexa |
|
||||
| **Cohere** | Conteúdo multilíngue | Excelente suporte a idiomas | Uso especializado |
|
||||
| **VoyageAI** | Tarefas de busca e recuperação | Otimizado para pesquisa | Provedor mais novo |
|
||||
|
||||
### Configuração via Variável de Ambiente
|
||||
|
||||
Para segurança, armazene chaves de API em variáveis de ambiente:
|
||||
|
||||
```python
|
||||
import os
|
||||
|
||||
# Configurar variáveis de ambiente
|
||||
os.environ["OPENAI_API_KEY"] = "your-openai-key"
|
||||
os.environ["GOOGLE_API_KEY"] = "your-google-key"
|
||||
os.environ["COHERE_API_KEY"] = "your-cohere-key"
|
||||
|
||||
# Use sem expor as chaves no código
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model": "text-embedding-3-small"
|
||||
# A chave de API será carregada automaticamente da variável de ambiente
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Testando Diferentes Provedores de Embedding
|
||||
|
||||
Compare provedores de embedding para o seu caso de uso específico:
|
||||
|
||||
```python
|
||||
from crewai import Crew
|
||||
from crewai.utilities.paths import db_storage_path
|
||||
|
||||
# Testar diferentes provedores com os mesmos dados
|
||||
providers_to_test = [
|
||||
{
|
||||
"name": "OpenAI",
|
||||
"config": {
|
||||
"provider": "openai",
|
||||
"config": {"model": "text-embedding-3-small"}
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "Ollama",
|
||||
"config": {
|
||||
"provider": "ollama",
|
||||
"config": {"model": "mxbai-embed-large"}
|
||||
}
|
||||
}
|
||||
]
|
||||
|
||||
for provider in providers_to_test:
|
||||
print(f"\nTesting {provider['name']} embeddings...")
|
||||
|
||||
# Criar crew com embedder específico
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
memory=True,
|
||||
embedder=provider['config']
|
||||
)
|
||||
|
||||
# Execute o teste e meça o desempenho
|
||||
result = crew.kickoff()
|
||||
print(f"{provider['name']} completed successfully")
|
||||
```
|
||||
|
||||
### Solução de Problemas de Embeddings
|
||||
|
||||
**Erros de modelo não encontrado:**
|
||||
```python
|
||||
# Verifique disponibilidade do modelo
|
||||
from crewai.utilities.embedding_configurator import EmbeddingConfigurator
|
||||
|
||||
configurator = EmbeddingConfigurator()
|
||||
try:
|
||||
embedder = configurator.configure_embedder({
|
||||
"provider": "ollama",
|
||||
"config": {"model": "mxbai-embed-large"}
|
||||
})
|
||||
print("Embedder configured successfully")
|
||||
except Exception as e:
|
||||
print(f"Configuration error: {e}")
|
||||
```
|
||||
|
||||
**Problemas com chave de API:**
|
||||
```python
|
||||
import os
|
||||
|
||||
# Verifique se as chaves de API estão configuradas
|
||||
required_keys = ["OPENAI_API_KEY", "GOOGLE_API_KEY", "COHERE_API_KEY"]
|
||||
for key in required_keys:
|
||||
if os.getenv(key):
|
||||
print(f"✅ {key} is set")
|
||||
else:
|
||||
print(f"❌ {key} is not set")
|
||||
```
|
||||
|
||||
**Comparação de desempenho:**
|
||||
```python
|
||||
import time
|
||||
|
||||
def test_embedding_performance(embedder_config, test_text="This is a test document"):
|
||||
start_time = time.time()
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
memory=True,
|
||||
embedder=embedder_config
|
||||
)
|
||||
|
||||
# Simula operação de memória
|
||||
crew.kickoff()
|
||||
|
||||
end_time = time.time()
|
||||
return end_time - start_time
|
||||
|
||||
# Comparar desempenho
|
||||
openai_time = test_embedding_performance({
|
||||
"provider": "openai",
|
||||
"config": {"model": "text-embedding-3-small"}
|
||||
})
|
||||
|
||||
ollama_time = test_embedding_performance({
|
||||
"provider": "ollama",
|
||||
"config": {"model": "mxbai-embed-large"}
|
||||
})
|
||||
|
||||
print(f"OpenAI: {openai_time:.2f}s")
|
||||
print(f"Ollama: {ollama_time:.2f}s")
|
||||
```
|
||||
|
||||
## 2. Memória de Usuário com Mem0 (Legado)
|
||||
|
||||
<Warning>
|
||||
**Abordagem Legada**: Embora totalmente funcional, esta abordagem é considerada legada. Para novos projetos que exijam memória específica do usuário, considere usar Memória Externa.
|
||||
</Warning>
|
||||
|
||||
A Memória de Usuário se integra com o [Mem0](https://mem0.ai/) para fornecer memória específica do usuário que persiste entre sessões e se integra ao sistema de memória contextual da crew.
|
||||
|
||||
### Pré-requisitos
|
||||
```bash
|
||||
pip install mem0ai
|
||||
```
|
||||
|
||||
### Configuração Mem0 na Nuvem
|
||||
```python
|
||||
import os
|
||||
from crewai import Crew, Process
|
||||
|
||||
# Defina sua chave de API do Mem0
|
||||
os.environ["MEM0_API_KEY"] = "m0-your-api-key"
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
memory=True, # Necessário para integração com a memória contextual
|
||||
memory_config={
|
||||
"provider": "mem0",
|
||||
"config": {"user_id": "john"},
|
||||
"user_memory": {} # Obrigatório - inicializa a memória de usuário
|
||||
},
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
### Configuração Avançada Mem0
|
||||
```python
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
memory=True,
|
||||
memory_config={
|
||||
"provider": "mem0",
|
||||
"config": {
|
||||
"user_id": "john",
|
||||
"org_id": "my_org_id", # Opcional
|
||||
"project_id": "my_project_id", # Opcional
|
||||
"api_key": "custom-api-key" # Opcional - sobrescreve variável de ambiente
|
||||
},
|
||||
"user_memory": {}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Configuração Mem0 Local
|
||||
```python
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
memory=True,
|
||||
memory_config={
|
||||
"provider": "mem0",
|
||||
"config": {
|
||||
"user_id": "john",
|
||||
"local_mem0_config": {
|
||||
"vector_store": {
|
||||
"provider": "qdrant",
|
||||
"config": {"host": "localhost", "port": 6333}
|
||||
},
|
||||
"llm": {
|
||||
"provider": "openai",
|
||||
"config": {"api_key": "your-api-key", "model": "gpt-4"}
|
||||
},
|
||||
"embedder": {
|
||||
"provider": "openai",
|
||||
"config": {"api_key": "your-api-key", "model": "text-embedding-3-small"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"user_memory": {}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## 3. Memória Externa (Nova Abordagem)
|
||||
|
||||
A Memória Externa fornece um sistema de memória autônomo que opera independentemente da memória interna da crew. Isso é ideal para provedores de memória especializados ou compartilhamento de memória entre aplicações.
|
||||
|
||||
### Memória Externa Básica com Mem0
|
||||
```python
|
||||
import os
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from crewai.memory.external.external_memory import ExternalMemory
|
||||
|
||||
os.environ["MEM0_API_KEY"] = "your-api-key"
|
||||
|
||||
# Criar instância de memória externa
|
||||
external_memory = ExternalMemory(
|
||||
embedder_config={
|
||||
"provider": "mem0",
|
||||
"config": {"user_id": "U-123"}
|
||||
}
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
external_memory=external_memory, # Independente da memória básica
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
### Implementação Personalizada de Armazenamento
|
||||
```python
|
||||
from crewai.memory.external.external_memory import ExternalMemory
|
||||
from crewai.memory.storage.interface import Storage
|
||||
|
||||
class CustomStorage(Storage):
|
||||
def __init__(self):
|
||||
self.memories = []
|
||||
|
||||
def save(self, value, metadata=None, agent=None):
|
||||
self.memories.append({
|
||||
"value": value,
|
||||
"metadata": metadata,
|
||||
"agent": agent
|
||||
})
|
||||
|
||||
def search(self, query, limit=10, score_threshold=0.5):
|
||||
# Implemente sua lógica de busca aqui
|
||||
return [m for m in self.memories if query.lower() in str(m["value"]).lower()]
|
||||
|
||||
def reset(self):
|
||||
self.memories = []
|
||||
|
||||
# Usando armazenamento customizado
|
||||
external_memory = ExternalMemory(storage=CustomStorage())
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
external_memory=external_memory
|
||||
)
|
||||
```
|
||||
|
||||
## Comparação dos Sistemas de Memória
|
||||
|
||||
| Recurso | Memória Básica | Memória de Usuário (Legado) | Memória Externa |
|
||||
|---------|---------------|-----------------------------|----------------|
|
||||
| **Complexidade de Setup** | Simples | Média | Média |
|
||||
| **Integração** | Contextual integrada | Contextual + específica do usuário | Autônoma |
|
||||
| **Armazenamento** | Arquivos locais | Mem0 Cloud/Local | Customizada/Mem0 |
|
||||
| **Multi-sessão** | ✅ | ✅ | ✅ |
|
||||
| **Especificidade do Usuário** | ❌ | ✅ | ✅ |
|
||||
| **Provedores Customizados** | Limitado | Apenas Mem0 | Qualquer provedor |
|
||||
| **Recomendado para** | Maioria dos casos | Projetos legados | Necessidades especializadas |
|
||||
|
||||
## Provedores de Embedding Suportados
|
||||
|
||||
### OpenAI (Padrão)
|
||||
```python
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "openai",
|
||||
"config": {"model": "text-embedding-3-small"}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Ollama
|
||||
```python
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "ollama",
|
||||
"config": {"model": "mxbai-embed-large"}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Google AI
|
||||
```python
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "google",
|
||||
"config": {
|
||||
"api_key": "your-api-key",
|
||||
"model": "text-embedding-004"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Azure OpenAI
|
||||
```python
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"api_key": "your-api-key",
|
||||
"api_base": "https://your-resource.openai.azure.com/",
|
||||
"api_version": "2023-05-15",
|
||||
"model_name": "text-embedding-3-small"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Vertex AI
|
||||
```python
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "vertexai",
|
||||
"config": {
|
||||
"project_id": "your-project-id",
|
||||
"region": "your-region",
|
||||
"api_key": "your-api-key",
|
||||
"model_name": "textembedding-gecko"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Melhores Práticas de Segurança
|
||||
|
||||
### Variáveis de Ambiente
|
||||
```python
|
||||
import os
|
||||
from crewai import Crew
|
||||
|
||||
# Armazene dados sensíveis em variáveis de ambiente
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
embedder={
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"api_key": os.getenv("OPENAI_API_KEY"),
|
||||
"model": "text-embedding-3-small"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Segurança no Armazenamento
|
||||
```python
|
||||
import os
|
||||
from crewai import Crew
|
||||
from crewai.memory import LongTermMemory
|
||||
from crewai.memory.storage.ltm_sqlite_storage import LTMSQLiteStorage
|
||||
|
||||
# Use caminhos seguros para armazenamento
|
||||
storage_path = os.getenv("CREWAI_STORAGE_DIR", "./storage")
|
||||
os.makedirs(storage_path, mode=0o700, exist_ok=True) # Permissões restritas
|
||||
|
||||
crew = Crew(
|
||||
memory=True,
|
||||
long_term_memory=LongTermMemory(
|
||||
storage=LTMSQLiteStorage(
|
||||
db_path=f"{storage_path}/memory.db"
|
||||
)
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Problemas Comuns
|
||||
|
||||
**A memória não está persistindo entre sessões?**
|
||||
- Verifique a variável de ambiente `CREWAI_STORAGE_DIR`
|
||||
- Garanta permissões de escrita no diretório de armazenamento
|
||||
- Certifique-se que a memória está ativada com `memory=True`
|
||||
|
||||
**Erros de autenticação no Mem0?**
|
||||
- Verifique se a variável de ambiente `MEM0_API_KEY` está definida
|
||||
- Confira permissões da chave de API no painel do Mem0
|
||||
- Certifique-se de que o pacote `mem0ai` está instalado
|
||||
|
||||
**Alto uso de memória com grandes volumes de dados?**
|
||||
- Considere usar Memória Externa com armazenamento personalizado
|
||||
- Implemente paginação nos métodos de busca do armazenamento customizado
|
||||
- Utilize modelos de embedding menores para menor consumo de memória
|
||||
|
||||
### Dicas de Desempenho
|
||||
|
||||
- Use `memory=True` para a maioria dos casos (mais simples e rápido)
|
||||
- Só utilize Memória de Usuário se precisar de persistência específica por usuário
|
||||
- Considere Memória Externa para necessidades de grande escala ou especializadas
|
||||
- Prefira modelos de embedding menores para maior rapidez
|
||||
- Defina limites apropriados de busca para controlar o tamanho da recuperação
|
||||
|
||||
## Benefícios do Sistema de Memória do CrewAI
|
||||
|
||||
- 🦾 **Aprendizado Adaptativo:** As crews tornam-se mais eficientes ao longo do tempo, adaptando-se a novas informações e refinando sua abordagem para tarefas.
|
||||
- 🫡 **Personalização Avançada:** A memória permite que agentes lembrem preferências do usuário e interações passadas, proporcionando experiências personalizadas.
|
||||
- 🧠 **Melhoria na Resolução de Problemas:** O acesso a um rico acervo de memória auxilia os agentes a tomar decisões mais informadas, recorrendo a aprendizados prévios e contextuais.
|
||||
|
||||
## Conclusão
|
||||
|
||||
Integrar o sistema de memória do CrewAI em seus projetos é simples. Ao aproveitar os componentes e configurações oferecidos,
|
||||
você rapidamente capacita seus agentes a lembrar, raciocinar e aprender com suas interações, desbloqueando novos níveis de inteligência e capacidade.
|
||||
152
docs/pt-BR/concepts/planning.mdx
Normal file
152
docs/pt-BR/concepts/planning.mdx
Normal file
@@ -0,0 +1,152 @@
|
||||
---
|
||||
title: Planejamento
|
||||
description: Aprenda como adicionar planejamento à sua CrewAI Crew e melhorar sua performance.
|
||||
icon: ruler-combined
|
||||
---
|
||||
|
||||
## Visão geral
|
||||
|
||||
O recurso de planejamento no CrewAI permite que você adicione capacidade de planejamento à sua crew. Quando ativado, antes de cada iteração da Crew, todas as informações da Crew são enviadas para um AgentPlanner que irá planejar as tarefas passo a passo, e este plano será adicionado à descrição de cada tarefa.
|
||||
|
||||
### Usando o recurso de Planejamento
|
||||
|
||||
Começar a usar o recurso de planejamento é muito simples, o único passo necessário é adicionar `planning=True` à sua Crew:
|
||||
|
||||
<CodeGroup>
|
||||
```python Code
|
||||
from crewai import Crew, Agent, Task, Process
|
||||
|
||||
# Monte sua crew com capacidades de planejamento
|
||||
my_crew = Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
planning=True,
|
||||
)
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
A partir deste ponto, sua crew terá o planejamento ativado, e as tarefas serão planejadas antes de cada iteração.
|
||||
|
||||
<Warning>
|
||||
Quando o planejamento está ativado, o crewAI irá usar `gpt-4o-mini` como o LLM padrão para planejamento, o que requer uma chave de API válida da OpenAI. Como seus agentes podem estar usando LLMs diferentes, isso pode causar confusão se você não tiver uma chave de API da OpenAI configurada ou se estiver experimentando um comportamento inesperado relacionado a chamadas de API de LLM.
|
||||
</Warning>
|
||||
|
||||
#### LLM de Planejamento
|
||||
|
||||
Agora você pode definir qual LLM será usado para planejar as tarefas.
|
||||
|
||||
Ao executar o exemplo básico, você verá algo semelhante ao resultado abaixo, que representa a saída do `AgentPlanner` responsável por criar a lógica passo a passo a ser adicionada às tarefas dos Agents.
|
||||
|
||||
<CodeGroup>
|
||||
```python Code
|
||||
from crewai import Crew, Agent, Task, Process
|
||||
|
||||
# Monte sua crew com capacidades de planejamento e LLM personalizado
|
||||
my_crew = Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
planning=True,
|
||||
planning_llm="gpt-4o"
|
||||
)
|
||||
|
||||
# Execute a crew
|
||||
my_crew.kickoff()
|
||||
```
|
||||
|
||||
```markdown Result
|
||||
[2024-07-15 16:49:11][INFO]: Planejando a execução da crew
|
||||
**Plano Passo a Passo para Execução das Tarefas**
|
||||
|
||||
**Tarefa Número 1: Realizar uma pesquisa aprofundada sobre LLMs de IA**
|
||||
|
||||
**Agente:** Pesquisador Sênior de Dados de LLMs de IA
|
||||
|
||||
**Objetivo do Agente:** Descobrir avanços de ponta em LLMs de IA
|
||||
|
||||
**Resultado Esperado da Tarefa:** Uma lista com 10 tópicos dos dados mais relevantes sobre LLMs de IA
|
||||
|
||||
**Ferramentas da Tarefa:** Nenhuma especificada
|
||||
|
||||
**Ferramentas do Agente:** Nenhuma especificada
|
||||
|
||||
**Plano Passo a Passo:**
|
||||
|
||||
1. **Definir o Escopo da Pesquisa:**
|
||||
|
||||
- Determine as áreas específicas de LLMs de IA a focar, como avanços em arquitetura, casos de uso, considerações éticas e métricas de performance.
|
||||
|
||||
2. **Identificar Fontes Confiáveis:**
|
||||
|
||||
- Liste fontes confiáveis para pesquisa em IA, incluindo periódicos acadêmicos, relatórios da indústria, conferências (ex: NeurIPS, ACL), laboratórios de pesquisa em IA (ex: OpenAI, Google AI) e bancos de dados online (ex: IEEE Xplore, arXiv).
|
||||
|
||||
3. **Coletar Dados:**
|
||||
|
||||
- Procure pelos artigos, publicações e relatórios mais recentes publicados em 2024 e início de 2025.
|
||||
- Use palavras-chave como "Large Language Models 2025", "Avanços em LLM de IA", "Ética em IA 2025", etc.
|
||||
|
||||
4. **Analisar Resultados:**
|
||||
|
||||
- Leia e resuma os principais pontos de cada fonte.
|
||||
- Destaque novas técnicas, modelos e aplicações introduzidos no último ano.
|
||||
|
||||
5. **Organizar as Informações:**
|
||||
|
||||
- Categorize as informações em tópicos relevantes (ex: novas arquiteturas, implicações éticas, aplicações no mundo real).
|
||||
- Garanta que cada tópico seja conciso, mas informativo.
|
||||
|
||||
6. **Criar a Lista:**
|
||||
|
||||
- Compile os 10 dados mais relevantes em itens de uma lista.
|
||||
- Revise a lista para garantir clareza e relevância.
|
||||
|
||||
**Saída Esperada:**
|
||||
|
||||
Uma lista com 10 tópicos dos dados mais relevantes sobre LLMs de IA.
|
||||
|
||||
---
|
||||
|
||||
**Tarefa Número 2: Revise o contexto obtido e expanda cada tópico em uma seção completa para um relatório**
|
||||
|
||||
**Agente:** Analista de Relatórios de LLMs de IA
|
||||
|
||||
**Objetivo do Agente:** Criar relatórios detalhados baseados na análise de dados e pesquisa sobre LLMs de IA
|
||||
|
||||
**Resultado Esperado da Tarefa:** Um relatório completo com os principais tópicos, cada um com uma seção completa de informações. Formatado em markdown sem '```'
|
||||
|
||||
**Ferramentas da Tarefa:** Nenhuma especificada
|
||||
|
||||
**Ferramentas do Agente:** Nenhuma especificada
|
||||
|
||||
**Plano Passo a Passo:**
|
||||
|
||||
1. **Revisar os Tópicos:**
|
||||
- Leia atentamente a lista dos 10 tópicos fornecida pelo Pesquisador Sênior de Dados de LLMs de IA.
|
||||
|
||||
2. **Esboçar o Relatório:**
|
||||
- Crie um esboço com cada tópico como título principal da seção.
|
||||
- Planeje subseções sob cada título para abordar diferentes aspectos do tema.
|
||||
|
||||
3. **Pesquisar Detalhes Adicionais:**
|
||||
- Para cada tópico, conduza pesquisa adicional, se necessário, para reunir informações mais detalhadas.
|
||||
- Busque estudos de caso, exemplos e dados estatísticos para embasar cada seção.
|
||||
|
||||
4. **Redigir Seções Detalhadas:**
|
||||
- Expanda cada tópico em uma seção abrangente.
|
||||
- Certifique-se de que cada seção inclua introdução, explicação detalhada, exemplos e conclusão.
|
||||
- Utilize formatação markdown para títulos, subtítulos, listas e ênfase.
|
||||
|
||||
5. **Revisar e Editar:**
|
||||
- Revise o relatório para garantir clareza, coerência e correção.
|
||||
- Garanta uma sequência lógica de uma seção para a outra.
|
||||
- Formate o relatório conforme os padrões markdown.
|
||||
|
||||
6. **Finalizar o Relatório:**
|
||||
- Certifique-se de que o relatório está completo, com todas as seções expandidas e detalhadas.
|
||||
- Faça uma última verificação de formatação e ajustes necessários.
|
||||
|
||||
**Saída Esperada:**
|
||||
Um relatório completo com os principais tópicos, cada um com uma seção cheia de informações. Formatado em markdown sem '```'.
|
||||
```
|
||||
</CodeGroup>
|
||||
66
docs/pt-BR/concepts/processes.mdx
Normal file
66
docs/pt-BR/concepts/processes.mdx
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Processos
|
||||
description: Guia detalhado sobre o gerenciamento de fluxos de trabalho através de processos no CrewAI, com detalhes de implementação atualizados.
|
||||
icon: bars-staggered
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
<Tip>
|
||||
Processos orquestram a execução de tarefas por agentes, de maneira semelhante à gestão de projetos em equipes humanas.
|
||||
Esses processos garantem que as tarefas sejam distribuídas e executadas de forma eficiente, alinhadas a uma estratégia predefinida.
|
||||
</Tip>
|
||||
|
||||
## Implementações de Processos
|
||||
|
||||
- **Sequencial**: Executa tarefas de forma sequencial, garantindo que as tarefas sejam concluídas em uma progressão ordenada.
|
||||
- **Hierárquico**: Organiza tarefas em uma hierarquia gerencial, onde as tarefas são delegadas e executadas com base numa cadeia de comando estruturada. Um modelo de linguagem de gerente (`manager_llm`) ou um agente gerente personalizado (`manager_agent`) deve ser especificado na crew para habilitar o processo hierárquico, facilitando a criação e o gerenciamento de tarefas pelo gerente.
|
||||
- **Processo Consensual (Planejado)**: Visando a tomada de decisão colaborativa entre agentes para execução de tarefas, esse tipo de processo introduz uma abordagem democrática ao gerenciamento de tarefas dentro do CrewAI. Está planejado para desenvolvimento futuro e ainda não está implementado no código-fonte.
|
||||
|
||||
## O Papel dos Processos no Trabalho em Equipe
|
||||
Os processos permitem que agentes individuais atuem como uma unidade coesa, otimizando seus esforços para atingir objetivos comuns com eficiência e coerência.
|
||||
|
||||
## Atribuindo Processos a uma Crew
|
||||
Para atribuir um processo a uma crew, especifique o tipo de processo ao criar a crew para definir a estratégia de execução. Para um processo hierárquico, garanta a definição de `manager_llm` ou `manager_agent` para o agente gerente.
|
||||
|
||||
```python
|
||||
from crewai import Crew, Process
|
||||
|
||||
# Exemplo: Criando uma crew com processo sequencial
|
||||
crew = Crew(
|
||||
agents=my_agents,
|
||||
tasks=my_tasks,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
# Exemplo: Criando uma crew com processo hierárquico
|
||||
# Certifique-se de fornecer um manager_llm ou manager_agent
|
||||
crew = Crew(
|
||||
agents=my_agents,
|
||||
tasks=my_tasks,
|
||||
process=Process.hierarchical,
|
||||
manager_llm="gpt-4o"
|
||||
# ou
|
||||
# manager_agent=my_manager_agent
|
||||
)
|
||||
```
|
||||
**Nota:** Certifique-se de que `my_agents` e `my_tasks` estejam definidos antes de criar o objeto `Crew`, e para o processo hierárquico, é necessário também fornecer o `manager_llm` ou `manager_agent`.
|
||||
|
||||
## Processo Sequencial
|
||||
|
||||
Este método reflete fluxos de trabalho dinâmicos de equipes, progredindo nas tarefas de maneira cuidadosa e sistemática. A execução das tarefas segue a ordem preestabelecida na lista de tarefas, com a saída de uma tarefa servindo de contexto para a próxima.
|
||||
|
||||
Para personalizar o contexto das tarefas, utilize o parâmetro `context` na classe `Task` para especificar as saídas que devem ser usadas como contexto para as tarefas subsequentes.
|
||||
|
||||
## Processo Hierárquico
|
||||
|
||||
Emulando uma hierarquia corporativa, o CrewAI permite especificar um agente gerente personalizado ou criar um automaticamente, exigindo a especificação de um modelo de linguagem de gerente (`manager_llm`). Esse agente supervisiona a execução das tarefas, incluindo planejamento, delegação e validação. As tarefas não são pré-atribuídas; o gerente aloca tarefas aos agentes com base em suas capacidades, revisa as saídas e avalia a conclusão das tarefas.
|
||||
|
||||
## Classe Process: Visão Detalhada
|
||||
|
||||
A classe `Process` é implementada como uma enumeração (`Enum`), garantindo segurança de tipo e restringindo os valores de processos aos tipos definidos (`sequential`, `hierarchical`). O processo consensual está planejado para inclusão futura, reforçando nosso compromisso com o desenvolvimento contínuo e a inovação.
|
||||
|
||||
## Conclusão
|
||||
|
||||
A colaboração estruturada possibilitada pelos processos dentro do CrewAI é fundamental para permitir o trabalho em equipe sistemático entre agentes.
|
||||
Esta documentação foi atualizada para refletir os mais recentes recursos, melhorias e a planejada integração do Processo Consensual, garantindo que os usuários tenham acesso às informações mais atuais e abrangentes.
|
||||
147
docs/pt-BR/concepts/reasoning.mdx
Normal file
147
docs/pt-BR/concepts/reasoning.mdx
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: Reasoning
|
||||
description: "Aprenda como habilitar e usar o reasoning do agente para aprimorar a execução de tarefas."
|
||||
icon: brain
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O reasoning do agente é um recurso que permite que agentes reflitam sobre uma tarefa e criem um plano antes da execução. Isso ajuda os agentes a abordarem tarefas de forma mais metódica e garante que estejam preparados para realizar o trabalho atribuído.
|
||||
|
||||
## Uso
|
||||
|
||||
Para habilitar o reasoning para um agente, basta definir `reasoning=True` ao criar o agente:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
|
||||
agent = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze complex datasets and provide insights",
|
||||
backstory="You are an experienced data analyst with expertise in finding patterns in complex data.",
|
||||
reasoning=True, # Enable reasoning
|
||||
max_reasoning_attempts=3 # Optional: Set a maximum number of reasoning attempts
|
||||
)
|
||||
```
|
||||
|
||||
## Como Funciona
|
||||
|
||||
Quando o reasoning está habilitado, antes de executar uma tarefa, o agente irá:
|
||||
|
||||
1. Refletir sobre a tarefa e criar um plano detalhado
|
||||
2. Avaliar se está pronto para executar a tarefa
|
||||
3. Refinar o plano conforme necessário até estar pronto ou até o limite de max_reasoning_attempts ser atingido
|
||||
4. Inserir o plano de reasoning na descrição da tarefa antes da execução
|
||||
|
||||
Esse processo ajuda o agente a dividir tarefas complexas em etapas gerenciáveis e identificar potenciais desafios antes de começar.
|
||||
|
||||
## Opções de Configuração
|
||||
|
||||
<ParamField body="reasoning" type="bool" default="False">
|
||||
Ativa ou desativa o reasoning
|
||||
</ParamField>
|
||||
|
||||
<ParamField body="max_reasoning_attempts" type="int" default="None">
|
||||
Número máximo de tentativas para refinar o plano antes de prosseguir com a execução. Se None (padrão), o agente continuará refinando até que esteja pronto.
|
||||
</ParamField>
|
||||
|
||||
## Exemplo
|
||||
|
||||
Aqui está um exemplo completo:
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create an agent with reasoning enabled
|
||||
analyst = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze data and provide insights",
|
||||
backstory="You are an expert data analyst.",
|
||||
reasoning=True,
|
||||
max_reasoning_attempts=3 # Optional: Set a limit on reasoning attempts
|
||||
)
|
||||
|
||||
# Create a task
|
||||
analysis_task = Task(
|
||||
description="Analyze the provided sales data and identify key trends.",
|
||||
expected_output="A report highlighting the top 3 sales trends.",
|
||||
agent=analyst
|
||||
)
|
||||
|
||||
# Create a crew and run the task
|
||||
crew = Crew(agents=[analyst], tasks=[analysis_task])
|
||||
result = crew.kickoff()
|
||||
|
||||
print(result)
|
||||
```
|
||||
|
||||
## Tratamento de Erros
|
||||
|
||||
O processo de reasoning foi projetado para ser robusto, com tratamento de erros integrado. Se ocorrer um erro durante o reasoning, o agente prosseguirá com a execução da tarefa sem o plano de reasoning. Isso garante que as tarefas ainda possam ser executadas mesmo que o processo de reasoning falhe.
|
||||
|
||||
Veja como lidar com possíveis erros no seu código:
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task
|
||||
import logging
|
||||
|
||||
# Set up logging to capture any reasoning errors
|
||||
logging.basicConfig(level=logging.INFO)
|
||||
|
||||
# Create an agent with reasoning enabled
|
||||
agent = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze data and provide insights",
|
||||
reasoning=True,
|
||||
max_reasoning_attempts=3
|
||||
)
|
||||
|
||||
# Create a task
|
||||
task = Task(
|
||||
description="Analyze the provided sales data and identify key trends.",
|
||||
expected_output="A report highlighting the top 3 sales trends.",
|
||||
agent=agent
|
||||
)
|
||||
|
||||
# Execute the task
|
||||
# If an error occurs during reasoning, it will be logged and execution will continue
|
||||
result = agent.execute_task(task)
|
||||
```
|
||||
|
||||
## Exemplo de Saída de reasoning
|
||||
|
||||
Veja um exemplo de como pode ser um plano de reasoning para uma tarefa de análise de dados:
|
||||
|
||||
```
|
||||
Task: Analyze the provided sales data and identify key trends.
|
||||
|
||||
Reasoning Plan:
|
||||
I'll analyze the sales data to identify the top 3 trends.
|
||||
|
||||
1. Understanding of the task:
|
||||
I need to analyze sales data to identify key trends that would be valuable for business decision-making.
|
||||
|
||||
2. Key steps I'll take:
|
||||
- First, I'll examine the data structure to understand what fields are available
|
||||
- Then I'll perform exploratory data analysis to identify patterns
|
||||
- Next, I'll analyze sales by time periods to identify temporal trends
|
||||
- I'll also analyze sales by product categories and customer segments
|
||||
- Finally, I'll identify the top 3 most significant trends
|
||||
|
||||
3. Approach to challenges:
|
||||
- If the data has missing values, I'll decide whether to fill or filter them
|
||||
- If the data has outliers, I'll investigate whether they're valid data points or errors
|
||||
- If trends aren't immediately obvious, I'll apply statistical methods to uncover patterns
|
||||
|
||||
4. Use of available tools:
|
||||
- I'll use data analysis tools to explore and visualize the data
|
||||
- I'll use statistical tools to identify significant patterns
|
||||
- I'll use knowledge retrieval to access relevant information about sales analysis
|
||||
|
||||
5. Expected outcome:
|
||||
A concise report highlighting the top 3 sales trends with supporting evidence from the data.
|
||||
|
||||
READY: I am ready to execute the task.
|
||||
```
|
||||
|
||||
Esse plano de reasoning ajuda o agente a organizar sua abordagem para a tarefa, considerar possíveis desafios e garantir que entregará o resultado esperado.
|
||||
996
docs/pt-BR/concepts/tasks.mdx
Normal file
996
docs/pt-BR/concepts/tasks.mdx
Normal file
@@ -0,0 +1,996 @@
|
||||
---
|
||||
title: Tarefas
|
||||
description: Guia detalhado sobre como gerenciar e criar tarefas dentro do framework CrewAI.
|
||||
icon: list-check
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
No framework CrewAI, uma `Task` (Tarefa) é uma atribuição específica executada por um `Agent` (Agente).
|
||||
|
||||
As tarefas fornecem todos os detalhes necessários para sua execução, como descrição, agente responsável, ferramentas exigidas e mais, facilitando uma ampla gama de complexidades de ação.
|
||||
|
||||
As tarefas dentro do CrewAI podem ser colaborativas, exigindo que múltiplos agentes trabalhem juntos. Isso é gerenciado por meio das propriedades da tarefa e orquestrado pelo processo do Crew, potencializando o trabalho em equipe e a eficiência.
|
||||
|
||||
<Note type="info" title="Aprimoramento Empresarial: Construtor Visual de Tarefas">
|
||||
O CrewAI Enterprise inclui um Construtor Visual de Tarefas no Crew Studio, que simplifica a criação e o encadeamento de tarefas complexas. Projete seus fluxos de tarefas visualmente e teste-os em tempo real sem necessidade de escrever código.
|
||||
|
||||
|
||||
|
||||
O Construtor Visual de Tarefas permite:
|
||||
- Criação de tarefas via arrastar-e-soltar
|
||||
- Visualização de dependências e fluxo de tarefas
|
||||
- Testes e validações em tempo real
|
||||
- Fácil compartilhamento e colaboração
|
||||
</Note>
|
||||
|
||||
### Fluxo de Execução de Tarefas
|
||||
|
||||
As tarefas podem ser executadas de duas maneiras:
|
||||
- **Sequencial**: As tarefas são executadas na ordem em que são definidas
|
||||
- **Hierárquica**: As tarefas são atribuídas aos agentes com base em seus papéis e especialidades
|
||||
|
||||
O fluxo de execução é definido ao criar o crew:
|
||||
```python Code
|
||||
crew = Crew(
|
||||
agents=[agent1, agent2],
|
||||
tasks=[task1, task2],
|
||||
process=Process.sequential # ou Process.hierarchical
|
||||
)
|
||||
```
|
||||
|
||||
## Atributos da Tarefa
|
||||
|
||||
| Atributo | Parâmetros | Tipo | Descrição |
|
||||
| :------------------------------- | :---------------- | :--------------------------- | :----------------------------------------------------------------------------------------------------------------- |
|
||||
| **Descrição** | `description` | `str` | Uma declaração clara e concisa do que a tarefa envolve. |
|
||||
| **Saída Esperada** | `expected_output` | `str` | Uma descrição detalhada de como deve ser o resultado da tarefa concluída. |
|
||||
| **Nome** _(opcional)_ | `name` | `Optional[str]` | Um identificador de nome para a tarefa. |
|
||||
| **Agente** _(opcional)_ | `agent` | `Optional[BaseAgent]` | O agente responsável por executar a tarefa. |
|
||||
| **Ferramentas** _(opcional)_ | `tools` | `List[BaseTool]` | As ferramentas/recursos que o agente pode usar para esta tarefa. |
|
||||
| **Contexto** _(opcional)_ | `context` | `Optional[List["Task"]]` | Outras tarefas cujas saídas serão usadas como contexto para esta tarefa. |
|
||||
| **Execução Assíncrona** _(opc.)_ | `async_execution` | `Optional[bool]` | Se a tarefa deve ser executada de forma assíncrona. O padrão é False. |
|
||||
| **Input Humano** _(opcional)_ | `human_input` | `Optional[bool]` | Se a tarefa deve ter uma revisão humana da resposta final do agente. O padrão é False. |
|
||||
| **Markdown** _(opcional)_ | `markdown` | `Optional[bool]` | Se a tarefa deve instruir o agente a retornar a resposta final formatada em Markdown. O padrão é False. |
|
||||
| **Config** _(opcional)_ | `config` | `Optional[Dict[str, Any]]` | Parâmetros de configuração específicos da tarefa. |
|
||||
| **Arquivo de Saída** _(opcional)_| `output_file` | `Optional[str]` | Caminho do arquivo para armazenar a saída da tarefa. |
|
||||
| **Saída JSON** _(opcional)_ | `output_json` | `Optional[Type[BaseModel]]` | Um modelo Pydantic para estruturar a saída em JSON. |
|
||||
| **Output Pydantic** _(opcional)_ | `output_pydantic` | `Optional[Type[BaseModel]]` | Um modelo Pydantic para a saída da tarefa. |
|
||||
| **Callback** _(opcional)_ | `callback` | `Optional[Any]` | Função/objeto a ser executado após a conclusão da tarefa. |
|
||||
|
||||
## Criando Tarefas
|
||||
|
||||
Existem duas maneiras de criar tarefas no CrewAI: utilizando **configuração YAML (recomendado)** ou definindo-as **diretamente no código**.
|
||||
|
||||
### Configuração YAML (Recomendado)
|
||||
|
||||
Utilizar configuração YAML oferece uma forma mais limpa e de fácil manutenção para definir tarefas. Recomendamos fortemente esse método em seus projetos CrewAI.
|
||||
|
||||
Após criar seu projeto CrewAI conforme indicado na seção [Instalação](/pt-BR/installation), navegue até o arquivo `src/latest_ai_development/config/tasks.yaml` e modifique o template para refletir os requisitos específicos das tarefas.
|
||||
|
||||
<Note>
|
||||
Variáveis em seus arquivos YAML (como `{topic}`) serão substituídas por valores vindos dos seus inputs ao executar o crew:
|
||||
```python Code
|
||||
crew.kickoff(inputs={'topic': 'AI Agents'})
|
||||
```
|
||||
</Note>
|
||||
|
||||
Veja um exemplo de configuração de tarefas usando YAML:
|
||||
|
||||
```yaml tasks.yaml
|
||||
research_task:
|
||||
description: >
|
||||
Realize uma pesquisa detalhada sobre {topic}
|
||||
Certifique-se de encontrar informações interessantes e relevantes considerando
|
||||
que o ano atual é 2025.
|
||||
expected_output: >
|
||||
Uma lista com 10 tópicos em bullet points das informações mais relevantes sobre {topic}
|
||||
agent: researcher
|
||||
|
||||
reporting_task:
|
||||
description: >
|
||||
Revise o contexto recebido e expanda cada tópico em uma seção completa de um relatório.
|
||||
Certifique-se de que o relatório seja detalhado e contenha todas as informações relevantes.
|
||||
expected_output: >
|
||||
Um relatório completo com os principais tópicos, cada um com uma seção cheia de informações.
|
||||
Formatado em markdown sem '```'
|
||||
agent: reporting_analyst
|
||||
markdown: true
|
||||
output_file: report.md
|
||||
```
|
||||
|
||||
Para usar essa configuração YAML em seu código, crie uma classe crew que herda de `CrewBase`:
|
||||
|
||||
```python crew.py
|
||||
# src/latest_ai_development/crew.py
|
||||
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from crewai.project import CrewBase, agent, crew, task
|
||||
from crewai_tools import SerperDevTool
|
||||
|
||||
@CrewBase
|
||||
class LatestAiDevelopmentCrew():
|
||||
"""LatestAiDevelopment crew"""
|
||||
|
||||
@agent
|
||||
def researcher(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['researcher'], # type: ignore[index]
|
||||
verbose=True,
|
||||
tools=[SerperDevTool()]
|
||||
)
|
||||
|
||||
@agent
|
||||
def reporting_analyst(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['reporting_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 reporting_task(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['reporting_task'] # type: ignore[index]
|
||||
)
|
||||
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=[
|
||||
self.researcher(),
|
||||
self.reporting_analyst()
|
||||
],
|
||||
tasks=[
|
||||
self.research_task(),
|
||||
self.reporting_task()
|
||||
],
|
||||
process=Process.sequential
|
||||
)
|
||||
```
|
||||
|
||||
<Note>
|
||||
Os nomes usados em seus arquivos YAML (`agents.yaml` e `tasks.yaml`) devem corresponder aos nomes dos métodos no seu código Python.
|
||||
</Note>
|
||||
|
||||
### Definição Direta no Código (Alternativa)
|
||||
|
||||
Alternativamente, você pode definir tarefas diretamente no seu código sem usar configuração YAML:
|
||||
|
||||
```python task.py
|
||||
from crewai import Task
|
||||
|
||||
research_task = Task(
|
||||
description="""
|
||||
Realize uma pesquisa detalhada sobre AI Agents.
|
||||
Certifique-se de encontrar informações interessantes e relevantes considerando
|
||||
que o ano atual é 2025.
|
||||
""",
|
||||
expected_output="""
|
||||
Uma lista com 10 tópicos em bullet points das informações mais relevantes sobre AI Agents
|
||||
""",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
reporting_task = Task(
|
||||
description="""
|
||||
Revise o contexto recebido e expanda cada tópico em uma seção completa de um relatório.
|
||||
Certifique-se de que o relatório seja detalhado e contenha todas as informações relevantes.
|
||||
""",
|
||||
expected_output="""
|
||||
Um relatório completo com os principais tópicos, cada um com uma seção cheia de informações.
|
||||
""",
|
||||
agent=reporting_analyst,
|
||||
markdown=True, # Ativa formatação markdown para a saída final
|
||||
output_file="report.md"
|
||||
)
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Especifique diretamente um `agent` para a tarefa ou permita que o processo `hierarchical` do CrewAI decida com base em papéis, disponibilidade, etc.
|
||||
</Tip>
|
||||
|
||||
## Saída da Tarefa
|
||||
|
||||
Compreender as saídas das tarefas é crucial para construir fluxos de trabalho de IA eficazes. O CrewAI oferece uma maneira estruturada de lidar com resultados usando a classe `TaskOutput`, que suporta múltiplos formatos de saída e pode ser facilmente passada entre tarefas.
|
||||
|
||||
A saída de uma tarefa no framework CrewAI é encapsulada na classe `TaskOutput`. Essa classe fornece uma maneira estruturada de acessar os resultados da tarefa, incluindo vários formatos como saída bruta, JSON e modelos Pydantic.
|
||||
|
||||
Por padrão, o `TaskOutput` incluirá apenas a saída `raw`. Um `TaskOutput` só terá as saídas `pydantic` ou `json_dict` se o objeto original da `Task` estiver configurado com `output_pydantic` ou `output_json`, respectivamente.
|
||||
|
||||
### Atributos do Task Output
|
||||
|
||||
| Atributo | Parâmetros | Tipo | Descrição |
|
||||
| :---------------- | :------------- | :------------------------- | :------------------------------------------------------------------------------------------ |
|
||||
| **Description** | `description` | `str` | Descrição da tarefa. |
|
||||
| **Summary** | `summary` | `Optional[str]` | Resumo da tarefa, gerado automaticamente a partir das primeiras 10 palavras da descrição. |
|
||||
| **Raw** | `raw` | `str` | Saída bruta da tarefa. Este é o formato padrão da saída. |
|
||||
| **Pydantic** | `pydantic` | `Optional[BaseModel]` | Objeto modelo Pydantic representando a saída da tarefa de forma estruturada. |
|
||||
| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]` | Dicionário representando a saída da tarefa em JSON. |
|
||||
| **Agent** | `agent` | `str` | O agente que executou a tarefa. |
|
||||
| **Output Format** | `output_format`| `OutputFormat` | O formato da saída da tarefa, podendo ser RAW, JSON e Pydantic. O padrão é RAW. |
|
||||
|
||||
### Métodos e Propriedades da Tarefa
|
||||
|
||||
| Método/Propriedade | Descrição |
|
||||
| :----------------- | :--------------------------------------------------------------------------------------------- |
|
||||
| **json** | Retorna a representação da saída da tarefa em JSON como string, se o formato de saída for JSON.|
|
||||
| **to_dict** | Converte as saídas JSON e Pydantic para um dicionário. |
|
||||
| **str** | Retorna a representação em string da saída da tarefa, priorizando Pydantic, depois JSON, depois raw. |
|
||||
|
||||
### Acessando Saídas das Tarefas
|
||||
|
||||
Uma vez que a tarefa é executada, sua saída pode ser acessada pelo atributo `output` do objeto `Task`. A classe `TaskOutput` oferece várias formas de interagir e apresentar esse resultado.
|
||||
|
||||
#### Exemplo
|
||||
|
||||
```python Code
|
||||
# Exemplo de tarefa
|
||||
task = Task(
|
||||
description='Encontre e resuma as últimas notícias de IA',
|
||||
expected_output='Uma lista em bullet points com o resumo das 5 notícias mais importantes de IA',
|
||||
agent=research_agent,
|
||||
tools=[search_tool]
|
||||
)
|
||||
|
||||
# Executando o crew
|
||||
crew = Crew(
|
||||
agents=[research_agent],
|
||||
tasks=[task],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
result = crew.kickoff()
|
||||
|
||||
# Acessando a saída da tarefa
|
||||
task_output = task.output
|
||||
|
||||
print(f"Descrição da Tarefa: {task_output.description}")
|
||||
print(f"Resumo da Tarefa: {task_output.summary}")
|
||||
print(f"Saída Bruta: {task_output.raw}")
|
||||
if task_output.json_dict:
|
||||
print(f"Saída em JSON: {json.dumps(task_output.json_dict, indent=2)}")
|
||||
if task_output.pydantic:
|
||||
print(f"Saída Pydantic: {task_output.pydantic}")
|
||||
```
|
||||
|
||||
## Formatação Markdown na Saída
|
||||
|
||||
O parâmetro `markdown` ativa a formatação automática em markdown na saída das tarefas. Quando configurado como `True`, a tarefa irá instruir o agente a formatar a resposta final utilizando a sintaxe Markdown correta.
|
||||
|
||||
### Usando Formatação Markdown
|
||||
|
||||
```python Code
|
||||
# Exemplo de tarefa com formatação markdown ativada
|
||||
formatted_task = Task(
|
||||
description="Crie um relatório abrangente sobre tendências em IA",
|
||||
expected_output="Um relatório bem estruturado com títulos, seções e bullet points",
|
||||
agent=reporter_agent,
|
||||
markdown=True # Habilita a formatação automática em markdown
|
||||
)
|
||||
```
|
||||
|
||||
Quando `markdown=True`, o agente recebe instruções extras para formatar a saída usando:
|
||||
- `#` para títulos
|
||||
- `**texto**` para negrito
|
||||
- `*texto*` para itálico
|
||||
- `-` ou `*` para bullet points
|
||||
- `` `código` `` para código inline
|
||||
- ``` ```linguagem ``` para blocos de código
|
||||
|
||||
### Configuração YAML com Markdown
|
||||
|
||||
```yaml tasks.yaml
|
||||
analysis_task:
|
||||
description: >
|
||||
Analise os dados de mercado e crie um relatório detalhado
|
||||
expected_output: >
|
||||
Uma análise completa com gráficos e descobertas-chave
|
||||
agent: analyst
|
||||
markdown: true # Habilita formatação em markdown
|
||||
output_file: analysis.md
|
||||
```
|
||||
|
||||
### Benefícios da Saída Markdown
|
||||
|
||||
- **Formatação Consistente**: Garante que todas as saídas sigam as convenções de markdown
|
||||
- **Maior Legibilidade**: Conteúdo estruturado com títulos, listas e ênfase
|
||||
- **Pronto para Documentação**: A saída pode ser usada diretamente em sistemas de documentação
|
||||
- **Compatibilidade Multi-plataforma**: Markdown é universalmente suportado
|
||||
|
||||
<Note>
|
||||
As instruções de formatação em markdown são adicionadas automaticamente ao prompt da tarefa quando `markdown=True`, então não é necessário detalhar os requisitos de formatação na descrição da tarefa.
|
||||
</Note>
|
||||
|
||||
## Dependências de Tarefas e Contexto
|
||||
|
||||
As tarefas podem depender da saída de outras tarefas utilizando o atributo `context`. Por exemplo:
|
||||
|
||||
```python Code
|
||||
research_task = Task(
|
||||
description="Pesquise os últimos avanços em IA",
|
||||
expected_output="Uma lista de avanços recentes em IA",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
analysis_task = Task(
|
||||
description="Analise os achados da pesquisa e identifique as tendências principais",
|
||||
expected_output="Relatório de análise das tendências em IA",
|
||||
agent=analyst,
|
||||
context=[research_task] # Esta tarefa aguardará a conclusão da research_task
|
||||
)
|
||||
```
|
||||
|
||||
## Guardrails em Tarefas
|
||||
|
||||
Guardrails (trilhas de proteção) de tarefas fornecem uma maneira de validar e transformar as saídas das tarefas antes que elas sejam passadas para a próxima tarefa. Esse recurso assegura a qualidade dos dados e oferece feedback aos agentes quando sua saída não atende a critérios específicos.
|
||||
|
||||
### Usando Guardrails em Tarefas
|
||||
|
||||
Para adicionar um guardrail a uma tarefa, forneça uma função de validação por meio do parâmetro `guardrail`:
|
||||
|
||||
```python Code
|
||||
from typing import Tuple, Union, Dict, Any
|
||||
from crewai import TaskOutput
|
||||
|
||||
def validate_blog_content(result: TaskOutput) -> Tuple[bool, Any]:
|
||||
"""Valida se o conteúdo do blog atende aos requisitos."""
|
||||
try:
|
||||
# Verifica a contagem de palavras
|
||||
word_count = len(result.split())
|
||||
if word_count > 200:
|
||||
return (False, "O conteúdo do blog excede 200 palavras")
|
||||
|
||||
# Lógica adicional de validação aqui
|
||||
return (True, result.strip())
|
||||
except Exception as e:
|
||||
return (False, "Erro inesperado durante a validação")
|
||||
|
||||
blog_task = Task(
|
||||
description="Escreva um post de blog sobre IA",
|
||||
expected_output="Um post de blog com menos de 200 palavras",
|
||||
agent=blog_agent,
|
||||
guardrail=validate_blog_content # Adiciona a função guardrail
|
||||
)
|
||||
```
|
||||
|
||||
### Requisitos da Função Guardrail
|
||||
|
||||
1. **Assinatura da Função**:
|
||||
- Deve aceitar exatamente um parâmetro (a saída da tarefa)
|
||||
- Deve retornar uma tupla `(bool, Any)`
|
||||
- Type hints são recomendados, mas opcionais
|
||||
|
||||
2. **Valores de Retorno**:
|
||||
- Em caso de sucesso: retorna uma tupla `(True, resultado_validado)`
|
||||
- Em caso de falha: retorna uma tupla `(False, "mensagem de erro explicando a falha")`
|
||||
|
||||
### LLMGuardrail
|
||||
|
||||
A classe `LLMGuardrail` oferece um mecanismo robusto para validação das saídas das tarefas.
|
||||
|
||||
### Melhores Práticas de Tratamento de Erros
|
||||
|
||||
1. **Respostas de Erro Estruturadas**:
|
||||
```python Code
|
||||
from crewai import TaskOutput, LLMGuardrail
|
||||
|
||||
def validate_with_context(result: TaskOutput) -> Tuple[bool, Any]:
|
||||
try:
|
||||
# Lógica principal de validação
|
||||
validated_data = perform_validation(result)
|
||||
return (True, validated_data)
|
||||
except ValidationError as e:
|
||||
return (False, f"VALIDATION_ERROR: {str(e)}")
|
||||
except Exception as e:
|
||||
return (False, str(e))
|
||||
```
|
||||
|
||||
2. **Categorias de Erro**:
|
||||
- Use códigos de erro específicos
|
||||
- Inclua contexto relevante
|
||||
- Forneça feedback acionável
|
||||
|
||||
3. **Cadeia de Validação**:
|
||||
```python Code
|
||||
from typing import Any, Dict, List, Tuple, Union
|
||||
from crewai import TaskOutput
|
||||
|
||||
def complex_validation(result: TaskOutput) -> Tuple[bool, Any]:
|
||||
"""Encadeia múltiplas etapas de validação."""
|
||||
# Passo 1: Validação básica
|
||||
if not result:
|
||||
return (False, "Resultado vazio")
|
||||
|
||||
# Passo 2: Validação de conteúdo
|
||||
try:
|
||||
validated = validate_content(result)
|
||||
if not validated:
|
||||
return (False, "Conteúdo inválido")
|
||||
|
||||
# Passo 3: Validação de formato
|
||||
formatted = format_output(validated)
|
||||
return (True, formatted)
|
||||
except Exception as e:
|
||||
return (False, str(e))
|
||||
```
|
||||
|
||||
### Tratamento dos Resultados do Guardrail
|
||||
|
||||
Quando um guardrail retorna `(False, erro)`:
|
||||
1. O erro é enviado de volta para o agente
|
||||
2. O agente tenta corrigir o problema
|
||||
3. O processo se repete até:
|
||||
- O guardrail retornar `(True, resultado)`
|
||||
- O número máximo de tentativas ser atingido
|
||||
|
||||
Exemplo com manipulação de tentativas:
|
||||
```python Code
|
||||
from typing import Optional, Tuple, Union
|
||||
from crewai import TaskOutput, Task
|
||||
|
||||
def validate_json_output(result: TaskOutput) -> Tuple[bool, Any]:
|
||||
"""Valida e faz o parsing da saída como JSON."""
|
||||
try:
|
||||
# Tenta realizar o parsing como JSON
|
||||
data = json.loads(result)
|
||||
return (True, data)
|
||||
except json.JSONDecodeError as e:
|
||||
return (False, "Formato JSON inválido")
|
||||
|
||||
task = Task(
|
||||
description="Gere um relatório em JSON",
|
||||
expected_output="Um objeto JSON válido",
|
||||
agent=analyst,
|
||||
guardrail=validate_json_output,
|
||||
max_retries=3 # Limite de tentativas
|
||||
)
|
||||
```
|
||||
|
||||
## Obtendo Saídas Estruturadas e Consistentes das Tarefas
|
||||
|
||||
<Note>
|
||||
É importante também observar que a saída da última tarefa de um crew se torna a saída final do próprio crew.
|
||||
</Note>
|
||||
|
||||
### Usando `output_pydantic`
|
||||
A propriedade `output_pydantic` permite que você defina um modelo Pydantic que a saída da tarefa deve seguir. Isso garante que a saída seja não apenas estruturada, mas também validada de acordo com o modelo.
|
||||
|
||||
Veja um exemplo de uso do output_pydantic:
|
||||
|
||||
```python Code
|
||||
import json
|
||||
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from pydantic import BaseModel
|
||||
|
||||
|
||||
class Blog(BaseModel):
|
||||
title: str
|
||||
content: str
|
||||
|
||||
|
||||
blog_agent = Agent(
|
||||
role="Blog Content Generator Agent",
|
||||
goal="Gerar um título e conteúdo para blog",
|
||||
backstory="""Você é um especialista em criação de conteúdo, habilidoso em escrever posts de blogs engajadores e informativos.""",
|
||||
verbose=False,
|
||||
allow_delegation=False,
|
||||
llm="gpt-4o",
|
||||
)
|
||||
|
||||
task1 = Task(
|
||||
description="""Crie um título e conteúdo para blog sobre um tópico. Certifique-se de que o conteúdo tenha menos de 200 palavras.""",
|
||||
expected_output="Um título atraente e um conteúdo bem escrito para blog.",
|
||||
agent=blog_agent,
|
||||
output_pydantic=Blog,
|
||||
)
|
||||
|
||||
# Instanciando o crew com processo sequencial
|
||||
crew = Crew(
|
||||
agents=[blog_agent],
|
||||
tasks=[task1],
|
||||
verbose=True,
|
||||
process=Process.sequential,
|
||||
)
|
||||
|
||||
result = crew.kickoff()
|
||||
|
||||
# Opção 1: Acessando propriedades via indexação de dicionário
|
||||
print("Acessando propriedades - Opção 1")
|
||||
title = result["title"]
|
||||
content = result["content"]
|
||||
print("Título:", title)
|
||||
print("Conteúdo:", content)
|
||||
|
||||
# Opção 2: Acessando diretamente do modelo Pydantic
|
||||
print("Acessando propriedades - Opção 2")
|
||||
title = result.pydantic.title
|
||||
content = result.pydantic.content
|
||||
print("Título:", title)
|
||||
print("Conteúdo:", content)
|
||||
|
||||
# Opção 3: Usando o método to_dict()
|
||||
print("Acessando propriedades - Opção 3")
|
||||
output_dict = result.to_dict()
|
||||
title = output_dict["title"]
|
||||
content = output_dict["content"]
|
||||
print("Título:", title)
|
||||
print("Conteúdo:", content)
|
||||
|
||||
# Opção 4: Imprimindo o objeto Blog inteiro
|
||||
print("Acessando propriedades - Opção 5")
|
||||
print("Blog:", result)
|
||||
|
||||
```
|
||||
Neste exemplo:
|
||||
* Um modelo Pydantic Blog é definido com os campos title e content.
|
||||
* A tarefa task1 utiliza a propriedade output_pydantic para especificar que sua saída deve seguir o modelo Blog.
|
||||
* Após executar o crew, você pode acessar a saída estruturada de várias formas, como mostrado.
|
||||
|
||||
#### Explicação sobre o acesso à saída
|
||||
1. Indexação estilo dicionário: Acesse os campos diretamente usando result["nome_do_campo"]. Isso funciona porque a classe CrewOutput implementa o método __getitem__.
|
||||
2. Diretamente do modelo Pydantic: Acesse os atributos diretamente do objeto result.pydantic.
|
||||
3. Usando o método to_dict(): Converta a saída para um dicionário e acesse os campos.
|
||||
4. Imprimindo o objeto inteiro: Simplesmente imprima o objeto result para ver a saída estruturada.
|
||||
|
||||
### Usando `output_json`
|
||||
A propriedade `output_json` permite definir o formato de saída esperado em JSON. Isso garante que a saída da tarefa seja uma estrutura JSON válida que pode ser facilmente analisada e utilizada na aplicação.
|
||||
|
||||
Veja um exemplo de uso do `output_json`:
|
||||
|
||||
```python Code
|
||||
import json
|
||||
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from pydantic import BaseModel
|
||||
|
||||
|
||||
# Define o modelo Pydantic para o blog
|
||||
class Blog(BaseModel):
|
||||
title: str
|
||||
content: str
|
||||
|
||||
|
||||
# Define o agente
|
||||
blog_agent = Agent(
|
||||
role="Blog Content Generator Agent",
|
||||
goal="Gerar um título e conteúdo para blog",
|
||||
backstory="""Você é um especialista em criação de conteúdo, habilidoso em escrever posts de blogs engajadores e informativos.""",
|
||||
verbose=False,
|
||||
allow_delegation=False,
|
||||
llm="gpt-4o",
|
||||
)
|
||||
|
||||
# Define a tarefa com output_json configurado para o modelo Blog
|
||||
task1 = Task(
|
||||
description="""Crie um título e conteúdo para blog sobre um tópico. Certifique-se de que o conteúdo tenha menos de 200 palavras.""",
|
||||
expected_output="Um objeto JSON com os campos 'title' e 'content'.",
|
||||
agent=blog_agent,
|
||||
output_json=Blog,
|
||||
)
|
||||
|
||||
# Instancia o crew com processo sequencial
|
||||
crew = Crew(
|
||||
agents=[blog_agent],
|
||||
tasks=[task1],
|
||||
verbose=True,
|
||||
process=Process.sequential,
|
||||
)
|
||||
|
||||
# Executa o crew para realizar a tarefa
|
||||
result = crew.kickoff()
|
||||
|
||||
# Opção 1: Acessando propriedades via indexação de dicionário
|
||||
print("Acessando propriedades - Opção 1")
|
||||
title = result["title"]
|
||||
content = result["content"]
|
||||
print("Título:", title)
|
||||
print("Conteúdo:", content)
|
||||
|
||||
# Opção 2: Imprimindo o objeto Blog inteiro
|
||||
print("Acessando propriedades - Opção 2")
|
||||
print("Blog:", result)
|
||||
```
|
||||
|
||||
Neste exemplo:
|
||||
* Um modelo Pydantic Blog é definido com os campos title e content, usado para especificar a estrutura do JSON de saída.
|
||||
* A tarefa task1 utiliza a propriedade output_json para indicar que espera uma saída JSON que segue o modelo Blog.
|
||||
* Após executar o crew, você pode acessar a saída estruturada em JSON conforme demonstrado.
|
||||
|
||||
#### Explicação sobre o acesso à saída
|
||||
|
||||
1. Acessando propriedades via indexação de dicionário: Você pode acessar os campos diretamente usando result["nome_do_campo"]. Isso é possível pois a classe CrewOutput implementa o método __getitem__, permitindo tratar a saída como um dicionário. Nesse caso, estamos acessando title e content do resultado.
|
||||
2. Imprimindo o objeto Blog inteiro: Ao imprimir result, você obterá a representação em string do objeto CrewOutput. Como o método __str__ é implementado para retornar a saída em JSON, isso exibirá toda a saída como uma string formatada representando o objeto Blog.
|
||||
|
||||
---
|
||||
|
||||
Utilizando `output_pydantic` ou `output_json`, você garante que suas tarefas produzam saídas em um formato estruturado e consistente, facilitando o processamento e uso dos dados na sua aplicação ou entre múltiplas tarefas.
|
||||
|
||||
## Integrando Ferramentas com Tarefas
|
||||
|
||||
Utilize ferramentas do [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools) e [LangChain Tools](https://python.langchain.com/docs/integrations/tools) para ampliar o desempenho das tarefas e aprimorar a interação dos agentes.
|
||||
|
||||
## Criando uma Tarefa com Ferramentas
|
||||
|
||||
```python Code
|
||||
import os
|
||||
os.environ["OPENAI_API_KEY"] = "Sua Chave"
|
||||
os.environ["SERPER_API_KEY"] = "Sua Chave" # Chave serper.dev
|
||||
|
||||
from crewai import Agent, Task, Crew
|
||||
from crewai_tools import SerperDevTool
|
||||
|
||||
research_agent = Agent(
|
||||
role='Researcher',
|
||||
goal='Encontrar e resumir as últimas notícias de IA',
|
||||
backstory="""Você é um pesquisador em uma grande empresa.
|
||||
Sua responsabilidade é analisar dados e fornecer insights
|
||||
para o negócio.""",
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Para realizar buscas semânticas de um termo a partir de textos da internet
|
||||
search_tool = SerperDevTool()
|
||||
|
||||
task = Task(
|
||||
description='Encontre e resuma as últimas notícias de IA',
|
||||
expected_output='Uma lista em bullet points com o resumo das 5 notícias mais importantes de IA',
|
||||
agent=research_agent,
|
||||
tools=[search_tool]
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[research_agent],
|
||||
tasks=[task],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
result = crew.kickoff()
|
||||
print(result)
|
||||
```
|
||||
|
||||
Isso demonstra como tarefas com ferramentas específicas podem sobrescrever o conjunto padrão de um agente para uma execução mais personalizada da tarefa.
|
||||
|
||||
## Referenciando Outras Tarefas
|
||||
|
||||
No CrewAI, a saída de uma tarefa é automaticamente repassada para a próxima, mas você pode definir explicitamente de quais tarefas a saída deve ser utilizada como contexto por outra, inclusive múltiplas saídas.
|
||||
|
||||
É útil especialmente quando você precisa que uma tarefa dependa do resultado de outra que não é executada imediatamente antes dela. Isso é feito pelo atributo `context`:
|
||||
|
||||
```python Code
|
||||
# ...
|
||||
|
||||
research_ai_task = Task(
|
||||
description="Pesquise os avanços mais recentes em IA",
|
||||
expected_output="Uma lista de avanços recentes em IA",
|
||||
async_execution=True,
|
||||
agent=research_agent,
|
||||
tools=[search_tool]
|
||||
)
|
||||
|
||||
research_ops_task = Task(
|
||||
description="Pesquise os avanços mais recentes em AI Ops",
|
||||
expected_output="Uma lista de avanços recentes em AI Ops",
|
||||
async_execution=True,
|
||||
agent=research_agent,
|
||||
tools=[search_tool]
|
||||
)
|
||||
|
||||
write_blog_task = Task(
|
||||
description="Escreva um post de blog completo sobre a importância da IA e suas últimas notícias",
|
||||
expected_output="Post de blog completo com 4 parágrafos",
|
||||
agent=writer_agent,
|
||||
context=[research_ai_task, research_ops_task]
|
||||
)
|
||||
|
||||
#...
|
||||
```
|
||||
|
||||
## Execução Assíncrona
|
||||
|
||||
Você pode definir que uma tarefa seja executada de forma assíncrona. Isso significa que o crew não aguardará sua conclusão para seguir para a próxima tarefa. É útil para tarefas demoradas, ou que não são cruciais para as seguintes.
|
||||
|
||||
Depois, utilize o atributo `context` para indicar, em uma tarefa futura, que ela deve aguardar os resultados da tarefa assíncrona.
|
||||
|
||||
```python Code
|
||||
#...
|
||||
|
||||
list_ideas = Task(
|
||||
description="Liste 5 ideias interessantes para explorar em um artigo sobre IA.",
|
||||
expected_output="Lista em bullet points com 5 ideias para um artigo.",
|
||||
agent=researcher,
|
||||
async_execution=True # Será executada de forma assíncrona
|
||||
)
|
||||
|
||||
list_important_history = Task(
|
||||
description="Pesquise a história da IA e forneça os 5 eventos mais importantes.",
|
||||
expected_output="Lista em bullet points com 5 eventos importantes.",
|
||||
agent=researcher,
|
||||
async_execution=True # Será executada de forma assíncrona
|
||||
)
|
||||
|
||||
write_article = Task(
|
||||
description="Escreva um artigo sobre IA, sua história e ideias interessantes.",
|
||||
expected_output="Artigo de 4 parágrafos sobre IA.",
|
||||
agent=writer,
|
||||
context=[list_ideas, list_important_history] # Vai esperar o resultado das duas tarefas
|
||||
)
|
||||
|
||||
#...
|
||||
```
|
||||
|
||||
## Mecanismo de Callback
|
||||
|
||||
A função callback é executada após a conclusão da tarefa, permitindo acionar ações ou notificações baseadas no resultado da tarefa.
|
||||
|
||||
```python Code
|
||||
# ...
|
||||
|
||||
def callback_function(output: TaskOutput):
|
||||
# Realiza algo após a conclusão da tarefa
|
||||
# Exemplo: Envia um e-mail ao gerente
|
||||
print(f"""
|
||||
Tarefa concluída!
|
||||
Tarefa: {output.description}
|
||||
Saída: {output.raw}
|
||||
""")
|
||||
|
||||
research_task = Task(
|
||||
description='Encontre e resuma as últimas notícias de IA',
|
||||
expected_output='Uma lista em bullet points com o resumo das 5 notícias mais importantes de IA',
|
||||
agent=research_agent,
|
||||
tools=[search_tool],
|
||||
callback=callback_function
|
||||
)
|
||||
|
||||
#...
|
||||
```
|
||||
|
||||
## Acessando a Saída de uma Tarefa Específica
|
||||
|
||||
Assim que um crew finaliza sua execução, você pode acessar a saída de uma tarefa específica por meio do atributo `output` do objeto da tarefa:
|
||||
|
||||
```python Code
|
||||
# ...
|
||||
task1 = Task(
|
||||
description='Encontre e resuma as últimas notícias de IA',
|
||||
expected_output='Uma lista em bullet points com o resumo das 5 notícias mais importantes de IA',
|
||||
agent=research_agent,
|
||||
tools=[search_tool]
|
||||
)
|
||||
|
||||
#...
|
||||
|
||||
crew = Crew(
|
||||
agents=[research_agent],
|
||||
tasks=[task1, task2, task3],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
result = crew.kickoff()
|
||||
|
||||
# Retorna um objeto TaskOutput com a descrição e resultado da tarefa
|
||||
print(f"""
|
||||
Tarefa concluída!
|
||||
Tarefa: {task1.output.description}
|
||||
Saída: {task1.output.raw}
|
||||
""")
|
||||
```
|
||||
|
||||
## Mecanismo de Sobrescrição de Ferramentas
|
||||
|
||||
Especificar ferramentas em uma tarefa permite a adaptação dinâmica das capacidades do agente, destacando a flexibilidade do CrewAI.
|
||||
|
||||
## Mecanismos de Validação e Tratamento de Erros
|
||||
|
||||
Ao criar e executar tarefas, determinados mecanismos de validação garantem a robustez e confiabilidade dos atributos das tarefas. Isso inclui, mas não se limita a:
|
||||
|
||||
- Garantir que apenas um tipo de saída seja definido por tarefa para manter expectativas de saída claras.
|
||||
- Impedir a atribuição manual do atributo `id`, preservando a integridade do sistema de identificadores únicos.
|
||||
|
||||
Estas validações colaboram para a consistência e confiabilidade das execuções de tarefas no framework CrewAI.
|
||||
|
||||
## Guardrails em Tarefas
|
||||
|
||||
Guardrails de tarefas oferecem uma maneira poderosa de validar, transformar ou filtrar as saídas das tarefas antes de serem encaminhadas à próxima. São funções opcionais que executam antes do início da próxima tarefa, garantindo que as saídas estejam em conformidade com requisitos ou formatos esperados.
|
||||
|
||||
### Uso Básico
|
||||
|
||||
#### Defina sua própria lógica de validação
|
||||
|
||||
```python Code
|
||||
from typing import Tuple, Union
|
||||
from crewai import Task
|
||||
|
||||
def validate_json_output(result: str) -> Tuple[bool, Union[dict, str]]:
|
||||
"""Valida se a saída é um JSON válido."""
|
||||
try:
|
||||
json_data = json.loads(result)
|
||||
return (True, json_data)
|
||||
except json.JSONDecodeError:
|
||||
return (False, "A saída deve ser um JSON válido")
|
||||
|
||||
task = Task(
|
||||
description="Gerar dados em JSON",
|
||||
expected_output="Objeto JSON válido",
|
||||
guardrail=validate_json_output
|
||||
)
|
||||
```
|
||||
|
||||
#### Use uma abordagem no-code para validação
|
||||
|
||||
```python Code
|
||||
from crewai import Task
|
||||
|
||||
task = Task(
|
||||
description="Gerar dados em JSON",
|
||||
expected_output="Objeto JSON válido",
|
||||
guardrail="Garanta que a resposta é um objeto JSON válido"
|
||||
)
|
||||
```
|
||||
|
||||
#### Usando YAML
|
||||
|
||||
```yaml
|
||||
research_task:
|
||||
...
|
||||
guardrail: garanta que cada bullet tenha no mínimo 100 palavras
|
||||
...
|
||||
```
|
||||
|
||||
```python Code
|
||||
@CrewBase
|
||||
class InternalCrew:
|
||||
agents_config = "config/agents.yaml"
|
||||
tasks_config = "config/tasks.yaml"
|
||||
|
||||
...
|
||||
@task
|
||||
def research_task(self):
|
||||
return Task(config=self.tasks_config["research_task"]) # type: ignore[index]
|
||||
...
|
||||
```
|
||||
|
||||
#### Use modelos customizados para geração de código
|
||||
|
||||
```python Code
|
||||
from crewai import Task
|
||||
from crewai.llm import LLM
|
||||
|
||||
task = Task(
|
||||
description="Gerar dados em JSON",
|
||||
expected_output="Objeto JSON válido",
|
||||
guardrail=LLMGuardrail(
|
||||
description="Garanta que a resposta é um objeto JSON válido",
|
||||
llm=LLM(model="gpt-4o-mini"),
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
### Como Guardrails Funcionam
|
||||
|
||||
1. **Atributo Opcional**: Guardrails são opcionais por tarefa, permitindo adicionar validação só onde for necessário.
|
||||
2. **Momento de Execução**: A função guardrail é executada antes do início da próxima tarefa, garantindo fluxo de dados válido entre tarefas.
|
||||
3. **Formato de Retorno**: Guardrails devem retornar uma tupla `(sucesso, dados)`:
|
||||
- Se `sucesso` é `True`, `dados` é o resultado validado/transformado
|
||||
- Se `sucesso` é `False`, `dados` é a mensagem de erro
|
||||
4. **Roteamento do Resultado**:
|
||||
- Sucesso (`True`): o resultado é automaticamente passado para a próxima tarefa
|
||||
- Falha (`False`): o erro é enviado de volta ao agente para gerar uma nova resposta
|
||||
|
||||
### Casos Comuns de Uso
|
||||
|
||||
#### Validação de Formato de Dados
|
||||
```python Code
|
||||
def validate_email_format(result: str) -> Tuple[bool, Union[str, str]]:
|
||||
"""Garante que a saída contenha um e-mail válido."""
|
||||
import re
|
||||
email_pattern = r'^[\w\.-]+@[\w\.-]+\.\w+$'
|
||||
if re.match(email_pattern, result.strip()):
|
||||
return (True, result.strip())
|
||||
return (False, "A saída deve ser um e-mail válido")
|
||||
```
|
||||
|
||||
#### Filtragem de Conteúdo
|
||||
```python Code
|
||||
def filter_sensitive_info(result: str) -> Tuple[bool, Union[str, str]]:
|
||||
"""Remove ou valida informações sensíveis."""
|
||||
sensitive_patterns = ['SSN:', 'password:', 'secret:']
|
||||
for pattern in sensitive_patterns:
|
||||
if pattern.lower() in result.lower():
|
||||
return (False, f"A saída contém informação sensível ({pattern})")
|
||||
return (True, result)
|
||||
```
|
||||
|
||||
#### Transformação de Dados
|
||||
```python Code
|
||||
def normalize_phone_number(result: str) -> Tuple[bool, Union[str, str]]:
|
||||
"""Garante que números de telefone estejam em formato consistente."""
|
||||
import re
|
||||
digits = re.sub(r'\D', '', result)
|
||||
if len(digits) == 10:
|
||||
formatted = f"({digits[:3]}) {digits[3:6]}-{digits[6:]}"
|
||||
return (True, formatted)
|
||||
return (False, "A saída deve ser um telefone com 10 dígitos")
|
||||
```
|
||||
|
||||
### Recursos Avançados
|
||||
|
||||
#### Encadeando Múltiplas Validações
|
||||
```python Code
|
||||
def chain_validations(*validators):
|
||||
"""Encadeia múltiplos validadores."""
|
||||
def combined_validator(result):
|
||||
for validator in validators:
|
||||
success, data = validator(result)
|
||||
if not success:
|
||||
return (False, data)
|
||||
result = data
|
||||
return (True, result)
|
||||
return combined_validator
|
||||
|
||||
# Uso
|
||||
task = Task(
|
||||
description="Obtenha informações de contato do usuário",
|
||||
expected_output="E-mail e telefone",
|
||||
guardrail=chain_validations(
|
||||
validate_email_format,
|
||||
filter_sensitive_info
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
#### Lógica Customizada de Retentativas
|
||||
```python Code
|
||||
task = Task(
|
||||
description="Gerar dados",
|
||||
expected_output="Dados válidos",
|
||||
guardrail=validate_data,
|
||||
max_retries=5 # Sobrescreve o limite padrão de tentativas
|
||||
)
|
||||
```
|
||||
|
||||
## Criando Diretórios ao Salvar Arquivos
|
||||
|
||||
Agora é possível especificar se uma tarefa deve criar diretórios ao salvar sua saída em arquivo. Isso é útil para organizar outputs e garantir que os caminhos estejam corretos.
|
||||
|
||||
```python Code
|
||||
# ...
|
||||
|
||||
save_output_task = Task(
|
||||
description='Salve o resumo das notícias de IA em um arquivo',
|
||||
expected_output='Arquivo salvo com sucesso',
|
||||
agent=research_agent,
|
||||
tools=[file_save_tool],
|
||||
output_file='outputs/ai_news_summary.txt',
|
||||
create_directory=True
|
||||
)
|
||||
|
||||
#...
|
||||
```
|
||||
|
||||
Veja o vídeo abaixo para aprender como utilizar saídas estruturadas no CrewAI:
|
||||
|
||||
<iframe
|
||||
width="560"
|
||||
height="315"
|
||||
src="https://www.youtube.com/embed/dNpKQk5uxHw"
|
||||
title="YouTube video player"
|
||||
frameborder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
referrerpolicy="strict-origin-when-cross-origin"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
|
||||
## Conclusão
|
||||
|
||||
Tarefas são a força motriz por trás das ações dos agentes no CrewAI.
|
||||
Ao definir corretamente as tarefas e seus resultados, você prepara seus agentes de IA para trabalhar de forma eficaz, seja de forma independente ou colaborativa.
|
||||
Equipar tarefas com as ferramentas adequadas, compreender o processo de execução e seguir práticas sólidas de validação são fundamentais para maximizar o potencial do CrewAI,
|
||||
assegurando que os agentes estejam devidamente preparados para suas atribuições e que as tarefas sejam executadas conforme o esperado.
|
||||
48
docs/pt-BR/concepts/testing.mdx
Normal file
48
docs/pt-BR/concepts/testing.mdx
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: Testes
|
||||
description: Saiba como testar sua CrewAI Crew e avaliar seu desempenho.
|
||||
icon: vial
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Testar é uma parte crucial do processo de desenvolvimento, sendo essencial para garantir que sua crew está performando conforme o esperado. Com o crewAI, você pode facilmente testar sua crew e avaliar seu desempenho utilizando as funcionalidades de teste integradas.
|
||||
|
||||
### Utilizando o Recurso de Teste
|
||||
|
||||
Adicionamos o comando de CLI `crewai test` para facilitar o teste da sua crew. Esse comando executará sua crew por um número especificado de iterações e fornecerá métricas de desempenho detalhadas. Os parâmetros são `n_iterations` e `model`, ambos opcionais e com valores padrão de 2 e `gpt-4o-mini`, respectivamente. Por enquanto, o único provedor disponível é a OpenAI.
|
||||
|
||||
```bash
|
||||
crewai test
|
||||
```
|
||||
|
||||
Se quiser rodar mais iterações ou utilizar um modelo diferente, você pode especificar os parâmetros assim:
|
||||
|
||||
```bash
|
||||
crewai test --n_iterations 5 --model gpt-4o
|
||||
```
|
||||
|
||||
ou usando as formas abreviadas:
|
||||
|
||||
```bash
|
||||
crewai test -n 5 -m gpt-4o
|
||||
```
|
||||
|
||||
Ao executar o comando `crewai test`, a crew será executada pelo número especificado de iterações, e as métricas de desempenho serão exibidas ao final da execução.
|
||||
|
||||
Uma tabela de pontuações ao final mostrará o desempenho da crew em relação às seguintes métricas:
|
||||
|
||||
<center>**Pontuações das Tarefas (1-10, quanto maior melhor)**</center>
|
||||
|
||||
| Tarefas/Crew/Agentes | Exec. 1 | Exec. 2 | Méd. Total | Agentes | Informações Adicionais |
|
||||
|:---------------------|:-------:|:-------:|:----------:|:------------------------------:|:---------------------------------|
|
||||
| Tarefa 1 | 9,0 | 9,5 | **9,2** | Professional Insights | |
|
||||
| | | | | Researcher | |
|
||||
| Tarefa 2 | 9,0 | 10,0 | **9,5** | Company Profile Investigator | |
|
||||
| Tarefa 3 | 9,0 | 9,0 | **9,0** | Automation Insights | |
|
||||
| | | | | Specialist | |
|
||||
| Tarefa 4 | 9,0 | 9,0 | **9,0** | Final Report Compiler | Automation Insights Specialist |
|
||||
| Crew | 9,00 | 9,38 | **9,2** | | |
|
||||
| Tempo de Execução (s)| 126 | 145 | **135** | | |
|
||||
|
||||
O exemplo acima mostra os resultados dos testes para duas execuções da crew com duas tarefas, apresentando a pontuação média total de cada tarefa e da crew como um todo.
|
||||
283
docs/pt-BR/concepts/tools.mdx
Normal file
283
docs/pt-BR/concepts/tools.mdx
Normal file
@@ -0,0 +1,283 @@
|
||||
---
|
||||
title: Ferramentas
|
||||
description: Compreendendo e aproveitando ferramentas dentro do framework CrewAI para colaboração e execução de tarefas por agentes.
|
||||
icon: screwdriver-wrench
|
||||
---
|
||||
|
||||
## Visão geral
|
||||
|
||||
As ferramentas do CrewAI capacitam agentes com habilidades que vão desde busca na web e análise de dados até colaboração e delegação de tarefas entre colegas de trabalho.
|
||||
Esta documentação descreve como criar, integrar e aproveitar essas ferramentas dentro do framework CrewAI, incluindo um novo foco em ferramentas de colaboração.
|
||||
|
||||
## O que é uma Ferramenta?
|
||||
|
||||
Uma ferramenta no CrewAI é uma habilidade ou função que os agentes podem utilizar para executar diversas ações.
|
||||
Isso inclui ferramentas do [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools) e [LangChain Tools](https://python.langchain.com/docs/integrations/tools),
|
||||
permitindo desde buscas simples até interações complexas e trabalho em equipe eficiente entre agentes.
|
||||
|
||||
<Note type="info" title="Aprimoramento para Empresas: Repositório de Ferramentas">
|
||||
O CrewAI Enterprise oferece um Repositório de Ferramentas abrangente, com integrações pré-construídas para sistemas empresariais e APIs comuns. Implemente agentes com ferramentas corporativas em minutos em vez de dias.
|
||||
|
||||
O Repositório de Ferramentas Empresariais inclui:
|
||||
- Conectores pré-construídos para sistemas empresariais populares
|
||||
- Interface para criação de ferramentas personalizadas
|
||||
- Controle de versão e funcionalidades de compartilhamento
|
||||
- Recursos de segurança e conformidade
|
||||
</Note>
|
||||
|
||||
## Características Principais das Ferramentas
|
||||
|
||||
- **Utilidade**: Desenvolvidas para tarefas como busca web, análise de dados, geração de conteúdo e colaboração entre agentes.
|
||||
- **Integração**: Potencializa as habilidades dos agentes ao integrar ferramentas de forma transparente ao seu fluxo de trabalho.
|
||||
- **Personalização**: Oferece flexibilidade para desenvolver ferramentas personalizadas ou utilizar existentes, atendendo necessidades específicas dos agentes.
|
||||
- **Tratamento de Erros**: Incorpora mecanismos robustos de tratamento de erros para garantir operação sem interrupções.
|
||||
- **Mecanismo de Cache**: Possui cache inteligente para otimizar desempenho e reduzir operações redundantes.
|
||||
- **Suporte Assíncrono**: Suporta ferramentas síncronas e assíncronas, permitindo operações não bloqueantes.
|
||||
|
||||
## Utilizando Ferramentas CrewAI
|
||||
|
||||
Para aprimorar as capacidades de seus agentes com as ferramentas do CrewAI, comece instalando nosso pacote extra de ferramentas:
|
||||
|
||||
```bash
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
Aqui está um exemplo demonstrando seu uso:
|
||||
|
||||
```python Code
|
||||
import os
|
||||
from crewai import Agent, Task, Crew
|
||||
# Importando ferramentas do crewAI
|
||||
from crewai_tools import (
|
||||
DirectoryReadTool,
|
||||
FileReadTool,
|
||||
SerperDevTool,
|
||||
WebsiteSearchTool
|
||||
)
|
||||
|
||||
# Configure as chaves de API
|
||||
os.environ["SERPER_API_KEY"] = "Your Key" # chave da API serper.dev
|
||||
os.environ["OPENAI_API_KEY"] = "Your Key"
|
||||
|
||||
# Instanciar as ferramentas
|
||||
docs_tool = DirectoryReadTool(directory='./blog-posts')
|
||||
file_tool = FileReadTool()
|
||||
search_tool = SerperDevTool()
|
||||
web_rag_tool = WebsiteSearchTool()
|
||||
|
||||
# Criar agentes
|
||||
researcher = Agent(
|
||||
role='Market Research Analyst',
|
||||
goal='Provide up-to-date market analysis of the AI industry',
|
||||
backstory='An expert analyst with a keen eye for market trends.',
|
||||
tools=[search_tool, web_rag_tool],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role='Content Writer',
|
||||
goal='Craft engaging blog posts about the AI industry',
|
||||
backstory='A skilled writer with a passion for technology.',
|
||||
tools=[docs_tool, file_tool],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Definir tarefas
|
||||
research = Task(
|
||||
description='Research the latest trends in the AI industry and provide a summary.',
|
||||
expected_output='A summary of the top 3 trending developments in the AI industry with a unique perspective on their significance.',
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
write = Task(
|
||||
description='Write an engaging blog post about the AI industry, based on the research analyst's summary. Draw inspiration from the latest blog posts in the directory.',
|
||||
expected_output='A 4-paragraph blog post formatted in markdown with engaging, informative, and accessible content, avoiding complex jargon.',
|
||||
agent=writer,
|
||||
output_file='blog-posts/new_post.md' # O post final do blog será salvo aqui
|
||||
)
|
||||
|
||||
# Montar um crew com o planejamento habilitado
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research, write],
|
||||
verbose=True,
|
||||
planning=True, # Habilitar o recurso de planejamento
|
||||
)
|
||||
|
||||
# Executar tarefas
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## Ferramentas CrewAI Disponíveis
|
||||
|
||||
- **Tratamento de Erros**: Todas as ferramentas são construídas com capacidades de tratamento de erros, permitindo que os agentes administrem exceções de forma adequada e prossigam com suas tarefas.
|
||||
- **Mecanismo de Cache**: Todas as ferramentas suportam cache, possibilitando que agentes reutilizem de forma eficiente resultados obtidos anteriormente, reduzindo a carga em recursos externos e acelerando o tempo de execução. Também é possível definir controles mais precisos sobre o mecanismo de cache usando o atributo `cache_function` na ferramenta.
|
||||
|
||||
Aqui está uma lista das ferramentas disponíveis e suas descrições:
|
||||
|
||||
| Ferramenta | Descrição |
|
||||
| :------------------------------- | :------------------------------------------------------------------------------------------- |
|
||||
| **ApifyActorsTool** | Ferramenta que integra Apify Actors aos seus fluxos de trabalho para web scraping e automação.|
|
||||
| **BrowserbaseLoadTool** | Ferramenta para interação e extração de dados de navegadores web. |
|
||||
| **CodeDocsSearchTool** | Uma ferramenta RAG otimizada para busca em documentações de código e documentos técnicos. |
|
||||
| **CodeInterpreterTool** | Ferramenta para interpretar código Python. |
|
||||
| **ComposioTool** | Permite o uso de ferramentas Composio. |
|
||||
| **CSVSearchTool** | Ferramenta RAG projetada para busca em arquivos CSV, ideal para dados estruturados. |
|
||||
| **DALL-E Tool** | Ferramenta para gerar imagens utilizando a API do DALL-E. |
|
||||
| **DirectorySearchTool** | Ferramenta RAG para busca em diretórios, útil para navegação em sistemas de arquivos. |
|
||||
| **DOCXSearchTool** | Ferramenta RAG voltada para busca em documentos DOCX, ideal para processar arquivos Word. |
|
||||
| **DirectoryReadTool** | Facilita a leitura e processamento de estruturas de diretórios e seus conteúdos. |
|
||||
| **EXASearchTool** | Ferramenta projetada para buscas exaustivas em diversas fontes de dados. |
|
||||
| **FileReadTool** | Permite a leitura e extração de dados de arquivos, suportando diversos formatos. |
|
||||
| **FirecrawlSearchTool** | Ferramenta para buscar páginas web usando Firecrawl e retornar os resultados. |
|
||||
| **FirecrawlCrawlWebsiteTool** | Ferramenta para rastrear páginas web utilizando o Firecrawl. |
|
||||
| **FirecrawlScrapeWebsiteTool** | Ferramenta para extrair o conteúdo de URLs usando Firecrawl. |
|
||||
| **GithubSearchTool** | Ferramenta RAG para buscar em repositórios GitHub, útil para pesquisa de código e documentação.|
|
||||
| **SerperDevTool** | Ferramenta especializada para finalidades de desenvolvimento, com funcionalidades em evolução. |
|
||||
| **TXTSearchTool** | Ferramenta RAG voltada para busca em arquivos de texto (.txt), adaptada para dados não estruturados. |
|
||||
| **JSONSearchTool** | Ferramenta RAG para busca em arquivos JSON, voltada ao manuseio de dados estruturados. |
|
||||
| **LlamaIndexTool** | Permite o uso das ferramentas LlamaIndex. |
|
||||
| **MDXSearchTool** | Ferramenta RAG para busca em arquivos Markdown (MDX), útil para documentação. |
|
||||
| **PDFSearchTool** | Ferramenta RAG para busca em documentos PDF, ideal para processar documentos digitalizados. |
|
||||
| **PGSearchTool** | Ferramenta RAG otimizada para busca em bancos de dados PostgreSQL, adequada para consultas. |
|
||||
| **Vision Tool** | Ferramenta para gerar imagens utilizando a API do DALL-E. |
|
||||
| **RagTool** | Ferramenta RAG de uso geral, capaz de lidar com diferentes fontes e tipos de dados. |
|
||||
| **ScrapeElementFromWebsiteTool** | Permite extrair elementos específicos de sites, útil para extração de dados direcionada. |
|
||||
| **ScrapeWebsiteTool** | Facilita o scraping de sites inteiros, ideal para coleta abrangente de dados. |
|
||||
| **WebsiteSearchTool** | Ferramenta RAG para busca em conteúdos de sites, otimizada para extração de dados web. |
|
||||
| **XMLSearchTool** | Ferramenta RAG para busca em arquivos XML, adequada para formatos de dados estruturados. |
|
||||
| **YoutubeChannelSearchTool** | Ferramenta RAG para busca em canais do YouTube, útil para análise de conteúdo em vídeo. |
|
||||
| **YoutubeVideoSearchTool** | Ferramenta RAG para busca em vídeos do YouTube, ideal para extração de dados de vídeo. |
|
||||
|
||||
## Criando suas próprias Ferramentas
|
||||
|
||||
<Tip>
|
||||
Desenvolvedores podem criar `ferramentas personalizadas` adaptadas para as necessidades de seus agentes ou utilizar opções pré-construídas.
|
||||
</Tip>
|
||||
|
||||
Existem duas formas principais de criar uma ferramenta CrewAI:
|
||||
|
||||
### Herança de `BaseTool`
|
||||
|
||||
```python Code
|
||||
from crewai.tools import BaseTool
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
class MyToolInput(BaseModel):
|
||||
"""Input schema for MyCustomTool."""
|
||||
argument: str = Field(..., description="Description of the argument.")
|
||||
|
||||
class MyCustomTool(BaseTool):
|
||||
name: str = "Name of my tool"
|
||||
description: str = "What this tool does. It's vital for effective utilization."
|
||||
args_schema: Type[BaseModel] = MyToolInput
|
||||
|
||||
def _run(self, argument: str) -> str:
|
||||
# Seu código da ferramenta aqui
|
||||
return "Tool's result"
|
||||
```
|
||||
|
||||
## Suporte a Ferramentas Assíncronas
|
||||
|
||||
O CrewAI suporta ferramentas assíncronas, permitindo que você implemente ferramentas que realizam operações não bloqueantes, como requisições de rede, I/O de arquivos ou outras operações async sem bloquear o fluxo principal de execução.
|
||||
|
||||
### Criando Ferramentas Assíncronas
|
||||
|
||||
Você pode criar ferramentas assíncronas de duas formas:
|
||||
|
||||
#### 1. Utilizando o Decorador `tool` com Funções Assíncronas
|
||||
|
||||
```python Code
|
||||
from crewai.tools import tool
|
||||
|
||||
@tool("fetch_data_async")
|
||||
async def fetch_data_async(query: str) -> str:
|
||||
"""Asynchronously fetch data based on the query."""
|
||||
# Simulate async operation
|
||||
await asyncio.sleep(1)
|
||||
return f"Data retrieved for {query}"
|
||||
```
|
||||
|
||||
#### 2. Implementando Métodos Assíncronos em Classes de Ferramentas Personalizadas
|
||||
|
||||
```python Code
|
||||
from crewai.tools import BaseTool
|
||||
|
||||
class AsyncCustomTool(BaseTool):
|
||||
name: str = "async_custom_tool"
|
||||
description: str = "An asynchronous custom tool"
|
||||
|
||||
async def _run(self, query: str = "") -> str:
|
||||
"""Asynchronously run the tool"""
|
||||
# Sua implementação assíncrona aqui
|
||||
await asyncio.sleep(1)
|
||||
return f"Processed {query} asynchronously"
|
||||
```
|
||||
|
||||
### Utilizando Ferramentas Assíncronas
|
||||
|
||||
Ferramentas assíncronas funcionam perfeitamente tanto em fluxos tradicionais do Crew quanto em fluxos baseados em Flow:
|
||||
|
||||
```python Code
|
||||
# No Crew tradicional
|
||||
agent = Agent(role="researcher", tools=[async_custom_tool])
|
||||
|
||||
# Em Flow
|
||||
class MyFlow(Flow):
|
||||
@start()
|
||||
async def begin(self):
|
||||
crew = Crew(agents=[agent])
|
||||
result = await crew.kickoff_async()
|
||||
return result
|
||||
```
|
||||
|
||||
O framework CrewAI lida automaticamente com a execução de ferramentas síncronas e assíncronas, então você não precisa se preocupar com diferenças na chamada.
|
||||
|
||||
### Utilizando o Decorador `tool`
|
||||
|
||||
```python Code
|
||||
from crewai.tools import tool
|
||||
@tool("Name of my tool")
|
||||
def my_tool(question: str) -> str:
|
||||
"""Clear description for what this tool is useful for, your agent will need this information to use it."""
|
||||
# Lógica da função aqui
|
||||
return "Result from your custom tool"
|
||||
```
|
||||
|
||||
### Mecanismo de Cache Personalizado
|
||||
|
||||
<Tip>
|
||||
As ferramentas podem implementar opcionalmente uma `cache_function` para ajuste fino do comportamento de cache.
|
||||
Esta função determina quando armazenar resultados em cache com base em condições específicas, oferecendo controle granular sobre a lógica de cache.
|
||||
</Tip>
|
||||
|
||||
```python Code
|
||||
from crewai.tools import tool
|
||||
|
||||
@tool
|
||||
def multiplication_tool(first_number: int, second_number: int) -> str:
|
||||
"""Useful for when you need to multiply two numbers together."""
|
||||
return first_number * second_number
|
||||
|
||||
def cache_func(args, result):
|
||||
# Neste exemplo, só cacheamos o resultado se for múltiplo de 2
|
||||
cache = result % 2 == 0
|
||||
return cache
|
||||
|
||||
multiplication_tool.cache_function = cache_func
|
||||
|
||||
writer1 = Agent(
|
||||
role="Writer",
|
||||
goal="You write lessons of math for kids.",
|
||||
backstory="You're an expert in writing and you love to teach kids but you know nothing of math.",
|
||||
tools=[multiplication_tool],
|
||||
allow_delegation=False,
|
||||
)
|
||||
#...
|
||||
```
|
||||
|
||||
## Conclusão
|
||||
|
||||
Ferramentas são fundamentais para expandir as capacidades dos agentes CrewAI, permitindo que assumam uma ampla gama de tarefas e colaborem de forma eficiente.
|
||||
Ao construir soluções com CrewAI, aproveite tanto ferramentas existentes quanto personalizadas para potencializar seus agentes e ampliar o ecossistema de IA. Considere utilizar tratamento de erros,
|
||||
mecanismos de cache e a flexibilidade de argumentos das ferramentas para otimizar o desempenho e as capacidades dos seus agentes.
|
||||
66
docs/pt-BR/concepts/training.mdx
Normal file
66
docs/pt-BR/concepts/training.mdx
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Treinamento
|
||||
description: Aprenda como treinar seus agentes CrewAI fornecendo feedback desde o início e obtenha resultados consistentes.
|
||||
icon: dumbbell
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O recurso de treinamento no CrewAI permite que você treine seus agentes de IA usando a interface de linha de comando (CLI).
|
||||
Ao executar o comando `crewai train -n <n_iterations>`, você pode especificar o número de iterações para o processo de treinamento.
|
||||
|
||||
Durante o treinamento, o CrewAI utiliza técnicas para otimizar o desempenho dos seus agentes juntamente com o feedback humano.
|
||||
Isso ajuda os agentes a aprimorar sua compreensão, tomada de decisão e habilidades de resolução de problemas.
|
||||
|
||||
### Treinando sua Crew Usando a CLI
|
||||
|
||||
Para utilizar o recurso de treinamento, siga estes passos:
|
||||
|
||||
1. Abra seu terminal ou prompt de comando.
|
||||
2. Navegue até o diretório onde seu projeto CrewAI está localizado.
|
||||
3. Execute o seguinte comando:
|
||||
|
||||
```shell
|
||||
crewai train -n <n_iterations> <filename> (optional)
|
||||
```
|
||||
<Tip>
|
||||
Substitua `<n_iterations>` pelo número desejado de iterações de treinamento e `<filename>` pelo nome de arquivo apropriado terminando com `.pkl`.
|
||||
</Tip>
|
||||
|
||||
### Treinando sua Crew Programaticamente
|
||||
|
||||
Para treinar sua crew de forma programática, siga estes passos:
|
||||
|
||||
1. Defina o número de iterações para o treinamento.
|
||||
2. Especifique os parâmetros de entrada para o processo de treinamento.
|
||||
3. Execute o comando de treinamento dentro de um bloco try-except para tratar possíveis erros.
|
||||
|
||||
```python Code
|
||||
n_iterations = 2
|
||||
inputs = {"topic": "CrewAI Training"}
|
||||
filename = "your_model.pkl"
|
||||
|
||||
try:
|
||||
YourCrewName_Crew().crew().train(
|
||||
n_iterations=n_iterations,
|
||||
inputs=inputs,
|
||||
filename=filename
|
||||
)
|
||||
|
||||
except Exception as e:
|
||||
raise Exception(f"An error occurred while training the crew: {e}")
|
||||
```
|
||||
|
||||
### Pontos Importantes
|
||||
|
||||
- **Requisito de Número Inteiro Positivo:** Certifique-se de que o número de iterações (`n_iterations`) seja um inteiro positivo. O código lançará um `ValueError` se essa condição não for atendida.
|
||||
- **Requisito de Nome de Arquivo:** Certifique-se de que o nome do arquivo termine com `.pkl`. O código lançará um `ValueError` se essa condição não for atendida.
|
||||
- **Tratamento de Erros:** O código trata erros de subprocessos e exceções inesperadas, fornecendo mensagens de erro ao usuário.
|
||||
|
||||
É importante observar que o processo de treinamento pode levar algum tempo, dependendo da complexidade dos seus agentes e também exigirá seu feedback em cada iteração.
|
||||
|
||||
Uma vez concluído o treinamento, seus agentes estarão equipados com capacidades e conhecimentos aprimorados, prontos para enfrentar tarefas complexas e fornecer insights mais consistentes e valiosos.
|
||||
|
||||
Lembre-se de atualizar e treinar seus agentes regularmente para garantir que permaneçam atualizados com as últimas informações e avanços na área.
|
||||
|
||||
Bom treinamento com o CrewAI! 🚀
|
||||
Reference in New Issue
Block a user