andre/crewAI
1
0
Fork 0
mirror of https://github.com/crewAIInc/crewAI.git synced 2026-01-09 08:08:32 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Add pt-BR docs translation (#3039)

Browse Source 
* 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
2025-06-25 12:52:33 -03:00
committed by GitHub
parent f6dfec61d6
commit a50fae3a4b
339 changed files with 33822 additions and 517 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
docs/pt-BR/api-reference/introduction.mdx Normal file
View File

@@ -0,0 +1,119 @@
---
title: "Introdução"
description: "Referência completa para a API REST do CrewAI Enterprise"
icon: "code"
---
# CrewAI Enterprise API
Bem-vindo à referência da API do CrewAI Enterprise. Esta API permite que você interaja programaticamente com seus crews implantados, possibilitando a integração com seus aplicativos, fluxos de trabalho e serviços.
## Início Rápido
<Steps>
<Step title="Obtenha suas credenciais de API">
Navegue até a página de detalhes do seu crew no painel do CrewAI Enterprise e copie seu Bearer Token na aba Status.
</Step>
<Step title="Descubra os Inputs Necessários">
Use o endpoint `GET /inputs` para ver quais parâmetros seu crew espera.
</Step>
<Step title="Inicie uma Execução de Crew">
Chame `POST /kickoff` com seus inputs para iniciar a execução do crew e receber um `kickoff_id`.
</Step>
<Step title="Monitore o Progresso">
Use `GET /status/{kickoff_id}` para checar o status da execução e recuperar os resultados.
</Step>
</Steps>
## Autenticação
Todas as requisições à API exigem autenticação usando um Bearer token. Inclua seu token no header `Authorization`:
```bash
curl -H "Authorization: Bearer YOUR_CREW_TOKEN" \
https://your-crew-url.crewai.com/inputs
```
### Tipos de Token
| Tipo de Token | Escopo | Caso de Uso |
|:--------------------|:------------------------|:---------------------------------------------------------|
| **Bearer Token** | Acesso em nível de organização | Operações completas de crew, ideal para integração server-to-server |
| **User Bearer Token** | Acesso com escopo de usuário | Permissões limitadas, adequado para operações específicas de usuário |
<Tip>
Você pode encontrar ambos os tipos de token na aba Status da página de detalhes do seu crew no painel do CrewAI Enterprise.
</Tip>
## URL Base
Cada crew implantado possui um endpoint de API único:
```
https://your-crew-name.crewai.com
```
Substitua `your-crew-name` pela URL real do seu crew no painel.
## Fluxo Típico
1. **Descoberta**: Chame `GET /inputs` para entender o que seu crew precisa
2. **Execução**: Envie os inputs via `POST /kickoff` para iniciar o processamento
3. **Monitoramento**: Faça polling em `GET /status/{kickoff_id}` até a conclusão
4. **Resultados**: Extraia o output final da resposta concluída
## Tratamento de Erros
A API utiliza códigos de status HTTP padrão:
| Código | Significado |
|--------|:--------------------------------------|
| `200` | Sucesso |
| `400` | Requisição Inválida - Formato de input inválido |
| `401` | Não Autorizado - Bearer token inválido |
| `404` | Não Encontrado - Recurso não existe |
| `422` | Erro de Validação - Inputs obrigatórios ausentes |
| `500` | Erro no Servidor - Contate o suporte |
## Testes Interativos
<Info>
**Por que não há botão "Enviar"?** Como cada usuário do CrewAI Enterprise possui sua própria URL de crew, utilizamos o **modo referência** em vez de um playground interativo para evitar confusão. Isso mostra exatamente como as requisições devem ser feitas, sem botões de envio não funcionais.
</Info>
Cada página de endpoint mostra para você:
- ✅ **Formato exato da requisição** com todos os parâmetros
- ✅ **Exemplos de resposta** para casos de sucesso e erro
- ✅ **Exemplos de código** em várias linguagens (cURL, Python, JavaScript, etc.)
- ✅ **Exemplos de autenticação** com o formato adequado de Bearer token
### **Para testar sua API de verdade:**
<CardGroup cols={2}>
<Card title="Copie Exemplos cURL" icon="terminal">
Copie os exemplos cURL e substitua a URL + token por seus valores reais
</Card>
<Card title="Use Postman/Insomnia" icon="play">
Importe os exemplos na sua ferramenta de testes de API preferida
</Card>
</CardGroup>
**Exemplo de fluxo:**
1. **Copie este exemplo cURL** de qualquer página de endpoint
2. **Substitua `your-actual-crew-name.crewai.com`** pela URL real do seu crew
3. **Substitua o Bearer token** pelo seu token real do painel
4. **Execute a requisição** no seu terminal ou cliente de API
## Precisa de Ajuda?
<CardGroup cols={2}>
<Card title="Suporte Enterprise" icon="headset" href="mailto:support@crewai.com">
Obtenha ajuda com integração da API e resolução de problemas
</Card>
<Card title="Painel Enterprise" icon="chart-line" href="https://app.crewai.com">
Gerencie seus crews e visualize logs de execução
</Card>
</CardGroup>

473
docs/pt-BR/changelog.mdx Normal file
View File

@@ -0,0 +1,473 @@
---
title: Registro de Alterações
description: Veja as atualizações e mudanças mais recentes do CrewAI
icon: timeline
---
<Update label="2024-05-22" description="v0.121.0" tags={["Latest"]}>
## Destaques da Versão
<Frame>
<img src="/images/releases/v01210.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.121.0">Ver no GitHub</a>
</div>
**Melhorias & Correções no Núcleo**
- Corrigido erro de codificação ao criar ferramentas
- Corrigido teste do llama com falha
- Configuração de logs atualizada para mais consistência
- Inicialização e tratamento de eventos de telemetria aprimorados
**Novas Funcionalidades & Aprimoramentos**
- Adicionado **atributo markdown** à classe Task
- Adicionado **atributo reasoning** à classe Agent
- Adicionada flag **inject_date** ao Agent para injeção automática de data
- Implementado **HallucinationGuardrail** (sem-operação, com cobertura de testes)
**Documentação & Guias**
- Documentação adicionada para **StagehandTool** e melhoria na estrutura MDX
- Inclusa documentação para integração **MCP** e atualização nos docs corporativos
- Eventos de conhecimento documentados e documentação de reasoning atualizada
- Adicionada explicação do parâmetro stop
- Corrigidas referências de import nos exemplos de documentação (before_kickoff, after_kickoff)
- Atualizações gerais e reestruturação nos docs para maior clareza
</Update>
<Update label="2024-05-15" description="v0.120.1">
## Destaques da Versão
<Frame>
<img src="/images/releases/v01201.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.120.1">Ver no GitHub</a>
</div>
**Melhorias & Correções no Núcleo**
- Corrigida **interpolação com hífens**
</Update>
<Update label="2024-05-14" description="v0.120.0">
## Destaques da Versão
<Frame>
<img src="/images/releases/v01200.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.120.0">Ver no GitHub</a>
</div>
**Melhorias & Correções no Núcleo**
- Conjunto completo de regras do Ruff habilitado por padrão para linting mais rigoroso
- Corrigida condição de corrida no FilteredStream usando context managers
- Corrigido problema de reset de conhecimento do agente
- Lógica de busca de agente refatorada para módulo utilitário
**Novas Funcionalidades & Aprimoramentos**
- Suporte adicionado para **carregar um Agent diretamente de um repositório**
- Permitida configuração de contexto vazio em Task
- Feedback do repositório de Agent aprimorado e correção no comportamento de auto-import de Tool
- Inicialização direta de conhecimento introduzida (bypassando knowledge_sources)
**Documentação & Guias**
- security.md atualizado para refletir práticas atuais de segurança
- Seção de configuração do Google revisada para mais clareza
- Adicionado link para AI Studio ao inserir chave Gemini
- Guia de observabilidade do Arize Phoenix atualizado
- Documentação de fluxo renovada
</Update>
<Update label="2024-05-08" description="v0.119.0">
## Destaques da Versão
<Frame>
<img src="/images/releases/v01190.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.119.0">Ver no GitHub</a>
</div>
**Melhorias & Correções no Núcleo**
- Confiabilidade de testes aprimorada melhorando o tratamento do pytest para testes instáveis
- Corrigido crash no reset de memória por incompatibilidade de dimensões de embeddings
- Identificação do fluxo pai habilitada para Crew e LiteAgent
- Crashes de telemetria prevenidos quando indisponíveis
- Atualização da versão do **LiteLLM** para melhor compatibilidade
- Corrigidos testes do conversor de llama removendo skip_external_api
**Novas Funcionalidades & Aprimoramentos**
- Introduzida **reescrita de prompt de recuperação de conhecimento** no Agent para melhor rastreamento e debug
- Guias de configuração do LLM e início rápido tornados independentes do modelo
**Documentação & Guias**
- Adicionada documentação de configuração avançada para o RAG tool
- Guia de resolução de problemas no Windows atualizado
- Exemplos na documentação refinados para maior clareza
- Correção de erros ortográficos em docs e arquivos de configuração
</Update>
<Update label="2024-04-28" description="v0.118.0">
## Destaques da Versão
<Frame>
<img src="/images/releases/v01180.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.118.0">Ver no GitHub</a>
</div>
**Melhorias & Correções no Núcleo**
- Corrigidos problemas com prompt ou templates de sistema ausentes
- Removida configuração global de logs para evitar sobreposição não intencional
- Renomeado **TaskGuardrail para LLMGuardrail** para maior clareza
- Versão do litellm rebaixada para 1.167.1 visando compatibilidade
- Adicionados arquivos init.py ausentes para garantir inicialização correta dos módulos
**Novas Funcionalidades & Aprimoramentos**
- Suporte adicionado para **criação de Guardrails sem código** facilitando o controle de comportamento da IA
**Documentação & Guias**
- CrewStructuredTool removido da documentação pública para refletir uso interno
- Documentação corporativa e embed do YouTube atualizados para melhor onboarding
</Update>
<Update label="2024-04-20" description="v0.117.0">
## Destaques da Versão
<Frame>
<img src="/images/releases/v01170.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.117.0">Ver no GitHub</a>
</div>
**Novas Funcionalidades & Aprimoramentos**
- Adicionado suporte ao parâmetro `result_as_answer` no decorator `@tool`.
- Suporte a novos modelos de linguagem: GPT-4.1, Gemini-2.0 e Gemini-2.5 Pro.
- Capacidades de gerenciamento de conhecimento aprimoradas.
- Adicionado provedor Huggingface na CLI.
- Compatibilidade e suporte CI melhorados para Python 3.10+.
**Melhorias & Correções no Núcleo**
- Corrigidos problemas com parâmetros de template incorretos e entradas ausentes.
- Fluxo assíncrono aprimorado com verificações de condição coroutine.
- Gerenciamento de memória aprimorado com configuração isolada e cópia correta dos objetos.
- Inicialização de lite agents corrigida com referências corretas.
- Corrigidos problemas de type hint em Python e remoção de imports redundantes.
- Atualização do posicionamento de eventos para rastreamento do uso de ferramentas.
- Exceções explícitas lançadas quando fluxos falham.
- Remoção de código e comentários redundantes em diversos módulos.
- Atualização da ação de token do GitHub App para v2.
**Documentação & Guias**
- Estrutura documental aprimorada, incluindo instruções para implantação corporativa.
- Criação automática de pastas de saída para geração de documentação.
- Link quebrado reparado na documentação do WeaviateVectorSearchTool.
- Correções na documentação do guardrail e nos caminhos de import dos search tools para JSON.
- Atualização na documentação do CodeInterpreterTool.
- Aprimoramento de SEO, navegação contextual e tratamento de erros nas páginas de documentação.
</Update>
<Update label="2024-04-25" description="v0.117.1">
## Destaques da Versão
<Frame>
<img src="/images/releases/v01171.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.117.1">Ver no GitHub</a>
</div>
**Melhorias & Correções no Núcleo**
- Versão do **crewai-tools** atualizada para a mais recente
- Versão do **liteLLM** atualizada para a mais recente
- Correção no **Mem0 OSS**
</Update>
<Update label="2024-04-07" description="v0.114.0">
## Destaques da Versão
<Frame>
<img src="/images/releases/v01140.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.114.0">Ver no GitHub</a>
</div>
**Novas Funcionalidades & Aprimoramentos**
- Agents como unidade atômica. (`Agent(...).kickoff()`)
- Suporte para [implementações Custom LLM](https://docs.crewai.com/guides/advanced/custom-llm).
- Memória externa integrada e [Opik observability](https://docs.crewai.com/how-to/opik-observability).
- Extração de YAML aprimorada.
- Validação multimodal de agentes.
- Impressões digitais seguras adicionadas para agents e crews.
**Melhorias & Correções no Núcleo**
- Serialização, cópia de agent e compatibilidade Python aprimoradas.
- Suporte a curingas adicionado a `emit()`
- Suporte a chamadas adicionais do roteador e ajustes de janela de contexto.
- Correções em typing, validação e imports.
- Melhoria na performance de métodos.
- Manipulação de tasks do agent, emissão de eventos e gerenciamento de memória aprimorados.
- Correções na CLI, tarefas condicionais, comportamento de clonagem e saídas de ferramentas.
**Documentação & Guias**
- Estrutura, tema e organização da documentação aprimorados.
- Guias para Local NVIDIA NIM com WSL2, W&B Weave e Arize Phoenix adicionados.
- Exemplos de configuração de ferramentas, prompts e docs de observabilidade atualizados.
- Guia para usar agentes singulares nos Flows.
</Update>
<Update label="2024-03-17" description="v0.108.0">
## Destaques da Versão
<Frame>
<img src="/images/releases/v01080.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.108.0">Ver no GitHub</a>
</div>
**Novas Funcionalidades & Aprimoramentos**
- Conversão de tabs para espaços no template `crew.py`
- Streaming de respostas LLM e sistema de eventos aprimorados
- Inclusão de `model_name`
- Event Listener aprimorado com visualização rica e logs melhorados
- Impressões digitais adicionadas
**Correções de Bugs**
- Correções de problemas com Mistral
- Correção de bug na documentação
- Correção de erro de type check na propriedade fingerprint
**Atualizações em Documentação**
- Documentação de ferramentas aprimorada
- Guia de instalação atualizado para o pacote `uv` tool
- Instruções adicionadas para upgrade do crewAI com o `uv` tool
- Documentação para `ApifyActorsTool` incluída
</Update>
<Update label="2024-03-10" description="v0.105.0">
## Destaques da Versão
<Frame>
<img src="/images/releases/v01050.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.105.0">Ver no GitHub</a>
</div>
**Melhorias & Correções no Núcleo**
- Correção de variáveis de template ausentes e configuração de memória de usuário
- Suporte a fluxo assíncrono melhorado e resolução para formatação de respostas do agente
- Função de reset de memória aprimorada e correção nos comandos de memória da CLI
- Correções em tipos, propriedades de chamadas de ferramenta e desacoplamento de telemetria
**Novas Funcionalidades & Aprimoramentos**
- Exportação de estado do Flow e utilitários de estado melhorados
- Configuração de conhecimento do agente aprimorada com embedder opcional para crew
- Emissor de eventos adicionado para melhor observabilidade e rastreamento de chamadas LLM
- Suporte para Python 3.10 e ChatOllama via langchain_ollama
- Suporte ao tamanho da janela de contexto para o modelo o3-mini
- Adicionada capacidade de múltiplas chamadas de roteador
**Documentação & Guias**
- Layout e estrutura hierárquica da documentação aprimorados
- Guia para QdrantVectorSearchTool incluído e uso de event listener esclarecido
- Correções de erros nos prompts e atualização da lista de modelos do Amazon Bedrock
</Update>
<Update label="2024-02-12" description="v0.102.0">
## Destaques da Versão
<Frame>
<img src="/images/releases/v01020.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.102.0">Ver no GitHub</a>
</div>
**Melhorias & Correções no Núcleo**
- Suporte LLM expandido: melhorar saída estruturada do LLM, manuseio de parâmetros e formatação para modelos Anthropic
- Estabilidade de Crew & Agent: corrigido clonagem de agents/crews com knowledge sources, múltiplas saídas de task em tarefas condicionais e callbacks de tarefa de Crew ignorados
- Correções de Memória & Armazenamento: melhora no gerenciamento de memória de curto prazo com Bedrock, inicialização correta do embedder e função reset memories adicionada na classe crew
- Confiabilidade em Treinamento & Execução: corrigidos treinamento quebrado e questões de interpolação com tipos de entrada dict e list
**Novas Funcionalidades & Aprimoramentos**
- Gerenciamento Avançado de Conhecimento: convencionamento de nomes melhorado e configuração de embedding aprimorada com suporte a embedder customizado
- Logging & Observabilidade Expandidos: suporte ao formato JSON para logging e documentação de rastreamento no MLflow integrada
- Melhorias no Tratamento de Dados: atualização do excel_knowledge_source.py para processar arquivos com múltipl abas
- Desempenho Geral & Limpeza do Código: alinhamento de código corporativo e resolução de problemas de linting
- Novo tool adicionado: `QdrantVectorSearchTool`
**Documentação & Guias**
- Docs de AI & Memória atualizados: melhorias em documentação do Bedrock, Google AI e memória de longo prazo
- Clareza em tarefas & fluxos: adicionada linha "Entrada Humana" em Task Attributes, guia para Langfuse e documentação para FileWriterTool
- Diversas correções de ortografia & formatação
</Update>
<Update label="2024-01-28" description="v0.100.0">
## Destaques da Versão
<Frame>
<img src="/images/releases/v01000.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.100.0">Ver no GitHub</a>
</div>
**Funcionalidades**
- Adição dos docs Composio
- Adicionado SageMaker como provedor LLM
**Correções**
- Correção geral nas conexões LLM
- Uso de acessores seguros no treinamento
- Checagem de versão adicionada ao crew_chat.py
**Documentação**
- Novos docs para crewai chat
- Melhorias no formato e clareza nos docs da CLI e da Composio Tool
</Update>
<Update label="2024-01-20" description="v0.98.0">
## Destaques da Versão
<Frame>
<img src="/images/releases/v0980.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.98.0">Ver no GitHub</a>
</div>
**Funcionalidades**
- Conversation crew v1
- Adição de ID único para estados de flow
- Adição do decorator @persist com a interface FlowPersistence
**Integrações**
- Integração SambaNova adicionada
- Novo provedor NVIDIA NIM na CLI
- Apresentando VoyageAI
**Correções**
- Correção de comportamento de chave API e tratamento de entidades na integração com Mem0
- Correção na lógica de invoke principal e nos testes relacionados
- Inputs de ferramentas agora são objetos reais em vez de strings
- Partes importantes adicionadas no processo de criação de ferramentas
- Versão do litellm foi rebaixada para prevenir problema no Windows
- Correção antes da execução caso inputs estejam nulos
- Corrigidos erros, modelo pydantic aninhado e falhas de docling
</Update>
<Update label="2024-01-04" description="v0.95.0">
## Destaques da Versão
<Frame>
<img src="/images/releases/v0950.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.95.0">Ver no GitHub</a>
</div>
**Novas Funcionalidades**
- Adição de habilidades multimodais ao Crew
- Guardrails programáticos
- HITL com múltiplas rodadas
- Suporte ao Gemini 2.0
- Melhorias em CrewAI Flows
- Permissões de workflow adicionadas
- Suporte a langfuse com litellm
- Integração Portkey com CrewAI
- Método interpolate_only e melhorias em tratamento de erros
- Suporte ao Docling
- Suporte ao Weviate
**Correções**
- output_file não respeitava caminho do sistema
- Erro de I/O em disco ao resetar memória de curto prazo
- CrewJSONEncoder agora aceita enums
- Versão máxima do Python
- Interpolação de output_file em Task
- Manipulação adequada de nomes de funções coworker quanto a caixa e espaços
- tiktoken adicionado como dependência explícita e documentação do requisito Rust
- Inclusão do conhecimento do agent no processo de planejamento
- Inicialização do armazenamento definida como None em KnowledgeStorage
- Verificações opcionais de armazenamento corrigidas
- Emissor de eventos incluído nos flows
- Melhorias em docstring, tratamento de erros e type hints
- Suppressão de userWarnings de problemas pydantic no litellm
</Update>
<Update label="2024-12-05" description="v0.86.0">
## Destaques da Versão
<Frame>
<img src="/images/releases/v0860.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.86.0">Ver no GitHub</a>
</div>
**Alterações**
- Removidas todas referências a pipeline e roteador de pipeline
- Adicionado Nvidia NIM como provedor em Custom LLM
- Adicionado demo de knowledge + melhorias nos docs de knowledge
- Adicionado suporte a múltiplas rodadas de HITL
- Novos docs sobre crew em yaml com decorators
- Template de crew simplificado
</Update>
<Update label="2024-12-04" description="v0.85.0">
## Destaques da Versão
<Frame>
<img src="/images/releases/v0850.png" />
</Frame>
<div style={{ textAlign: 'center', marginBottom: '1rem' }}>
<a href="https://github.com/crewAIInc/crewAI/releases/tag/0.85.0">Ver no GitHub</a>
</div>
**Funcionalidades**
- Adicionado conhecimento em nível de agent
- Feat/remover langchain
- Aprimoradas saídas tipadas das tasks
- Login no Tool Repository ao fazer login no crewai
**Correções**
- Correção em issues de result as answer não encerrando loop do LLM corretamente
- Correção de ausência de nome de chave ao rodar com o provedor ollama
- Correção em erro ortográfico identificado
**Documentação**
- Atualização no readme para rodar mypy
- Adição do conhecimento em mint.json
- Atualização das ações do Github
- Atualização na documentação de Agents para incluir duas abordagens na criação de agent
- Melhorias na Configuração e Uso do LLM
</Update>
<Update label="2024-11-25" description="v0.83.0">
**Novas Funcionalidades**
- Novos callbacks before_kickoff e after_kickoff em crew
- Suporte para pre-seed de agents com Knowledge
- Adicionado suporte para recuperação de preferências de usuário e memórias usando Mem0
**Correções**
- Correção em execução assíncrona
- Upgrade do chroma e ajuste no gerador de funções do embedder
- Atualização do CLI Watson com modelos suportados + docs
- Redução do nível para Bandit
- Correção de todos os testes
**Documentação**
- Documentação atualizada
</Update>
<Update label="2024-11-13" description="v0.80.0">
**Correções**
- Correção em bug de substituição do callback Tokens
- Correção em issue de callback Step
- Informação de prompt tokens em cache adicionada nas métricas de uso
- Correção no teste crew_train_success
</Update>

593
docs/pt-BR/concepts/agents.mdx Normal file
View 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.
![Visual Agent Builder Screenshot](/images/enterprise/crew-studio-interface.png)
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
View 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
View 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
View 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
View 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.
![Prompt Tracing Dashboard](/images/enterprise/traces-overview.png)
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
View 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>
![Flow Visual image](/images/crewai-flow-2.png)
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>
![Flow Visual image](/images/crewai-flow-2.png)
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)
```
![Flow Visual image](/images/crewai-flow-3.png)
**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)
```
![Flow Visual image](/images/crewai-flow-3.png)
**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>
![Flow Visual image](/images/crewai-flow-4.png)
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>
![Flow Visual image](/images/crewai-flow-5.png)
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>
![Flow Visual image](/images/crewai-flow-6.png)
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)
```
![Flow Visual image](/images/crewai-flow-7.png)
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()`.
![Flow Visual image](/images/crewai-flow-8.png)
### 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
View File

File diff suppressed because it is too large Load Diff

884
docs/pt-BR/concepts/llms.mdx Normal file
View 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
View 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
View 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
View 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
View 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
View 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.
![Task Builder Screenshot](/images/enterprise/crew-studio-interface.png)
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
View 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
View 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
View 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! 🚀

250
docs/pt-BR/enterprise/features/hallucination-guardrail.mdx Normal file
View File

@@ -0,0 +1,250 @@
---
title: Proteção contra Alucinações
description: "Previna e detecte alucinações de IA nas suas tarefas do CrewAI"
icon: "shield-check"
---
## Visão Geral
A Proteção contra Alucinações é um recurso empresarial que valida o conteúdo gerado por IA para garantir que esteja fundamentado em fatos e não contenha alucinações. Ela analisa as saídas das tarefas em relação ao contexto de referência e fornece feedback detalhado quando é detectado conteúdo potencialmente alucinado.
## O que são Alucinações?
Alucinações em IA ocorrem quando modelos de linguagem geram conteúdos que parecem plausíveis, mas estão factualmente incorretos ou não são suportados pelo contexto fornecido. A Proteção contra Alucinações ajuda a prevenir esses problemas por meio de:
- Comparação das saídas com o contexto de referência
- Avaliação da fidelidade ao material de origem
- Fornecimento de feedback detalhado sobre conteúdo problemático
- Suporte a limiares personalizados para rigor da validação
## Uso Básico
### Configurando a Proteção
```python
from crewai.tasks.hallucination_guardrail import HallucinationGuardrail
from crewai import LLM
# Uso básico - utiliza o expected_output da tarefa como contexto
guardrail = HallucinationGuardrail(
llm=LLM(model="gpt-4o-mini")
)
# Com contexto de referência explícito
context_guardrail = HallucinationGuardrail(
context="AI helps with various tasks including analysis and generation.",
llm=LLM(model="gpt-4o-mini")
)
```
### Adicionando às Tarefas
```python
from crewai import Task
# Crie sua tarefa com a proteção
task = Task(
description="Write a summary about AI capabilities",
expected_output="A factual summary based on the provided context",
agent=my_agent,
guardrail=guardrail # Adiciona a proteção para validar a saída
)
```
## Configuração Avançada
### Validação com Limiar Personalizado
Para validação mais rigorosa, é possível definir um limiar de fidelidade personalizado (escala de 0-10):
```python
# Proteção rigorosa exigindo alta pontuação de fidelidade
strict_guardrail = HallucinationGuardrail(
context="Quantum computing uses qubits that exist in superposition states.",
llm=LLM(model="gpt-4o-mini"),
threshold=8.0 # Requer pontuação >= 8 para validar
)
```
### Incluindo Contexto da Resposta de Ferramentas
Se sua tarefa utiliza ferramentas, você pode incluir as respostas das ferramentas para validação mais precisa:
```python
# Proteção com contexto de resposta da ferramenta
weather_guardrail = HallucinationGuardrail(
context="Current weather information for the requested location",
llm=LLM(model="gpt-4o-mini"),
tool_response="Weather API returned: Temperature 22°C, Humidity 65%, Clear skies"
)
```
## Como Funciona
### Processo de Validação
1. **Análise de Contexto**: A proteção compara a saída da tarefa com o contexto de referência fornecido
2. **Pontuação de Fidelidade**: Usa um avaliador interno para atribuir uma pontuação de fidelidade (0-10)
3. **Determinação do Veredito**: Determina se o conteúdo é fiel ou contém alucinações
4. **Verificação de Limiar**: Se um limiar personalizado for definido, valida contra essa pontuação
5. **Geração de Feedback**: Fornece motivos detalhados caso a validação falhe
### Lógica de Validação
- **Modo Padrão**: Utiliza validação baseada em veredito (FIÉL vs ALUCINADO)
- **Modo com Limiar**: Requer que a pontuação de fidelidade atinja ou supere o limiar especificado
- **Tratamento de Erros**: Lida com erros de avaliação de forma elegante e fornece feedback informativo
## Resultados da Proteção
A proteção retorna resultados estruturados indicando o status da validação:
```python
# Exemplo de estrutura de resultado da proteção
{
"valid": False,
"feedback": "Content appears to be hallucinated (score: 4.2/10, verdict: HALLUCINATED). The output contains information not supported by the provided context."
}
```
### Propriedades do Resultado
- **valid**: Booleano indicando se a saída passou na validação
- **feedback**: Explicação detalhada quando a validação falha, incluindo:
- Pontuação de fidelidade
- Classificação do veredito
- Motivos específicos para a falha
## Integração com o Sistema de Tarefas
### Validação Automática
Quando uma proteção é adicionada à tarefa, ela valida automaticamente a saída antes da tarefa ser marcada como concluída:
```python
# Fluxo de validação de saída da tarefa
task_output = agent.execute_task(task)
validation_result = guardrail(task_output)
if validation_result.valid:
# Tarefa concluída com sucesso
return task_output
else:
# Tarefa falha com feedback de validação
raise ValidationError(validation_result.feedback)
```
### Rastreamento de Eventos
A proteção se integra ao sistema de eventos do CrewAI para fornecer observabilidade:
- **Validação Iniciada**: Quando a avaliação da proteção começa
- **Validação Concluída**: Quando a avaliação termina com resultados
- **Falha na Validação**: Quando ocorrem erros técnicos durante a avaliação
## Melhores Práticas
### Diretrizes para o Contexto
<Steps>
<Step title="Forneça Contexto Abrangente">
Inclua todas as informações factuais relevantes nas quais a IA deve basear sua saída:
```python
context = """
Company XYZ was founded in 2020 and specializes in renewable energy solutions.
They have 150 employees and generated $50M revenue in 2023.
Their main products include solar panels and wind turbines.
"""
```
</Step>
<Step title="Mantenha o Contexto Relevante">
Inclua apenas informações diretamente relacionadas à tarefa para evitar confusão:
```python
# Bom: Contexto focado
context = "The current weather in New York is 18°C with light rain."
# Evite: Informações irrelevantes
context = "The weather is 18°C. The city has 8 million people. Traffic is heavy."
```
</Step>
<Step title="Atualize o Contexto Regularmente">
Certifique-se de que seu contexto de referência reflita informações atuais e precisas.
</Step>
</Steps>
### Seleção de Limiar
<Steps>
<Step title="Comece com a Validação Padrão">
Inicie sem limiares personalizados para entender a performance inicial.
</Step>
<Step title="Ajuste Conforme as Necessidades">
- **Conteúdo crítico**: Use limiar 8-10 para máxima precisão
- **Conteúdo geral**: Use limiar 6-7 para validação equilibrada
- **Conteúdo criativo**: Use limiar 4-5 ou validação padrão baseada em veredito
</Step>
<Step title="Monitore e Itere">
Acompanhe os resultados da validação e ajuste os limiares conforme falsos positivos/negativos.
</Step>
</Steps>
## Considerações de Performance
### Impacto no Tempo de Execução
- **Sobrecarga de Validação**: Cada proteção adiciona ~1-3 segundos por tarefa
- **Eficiência do LLM**: Escolha modelos eficientes para avaliação (ex: gpt-4o-mini)
### Otimização de Custos
- **Seleção de Modelo**: Utilize modelos menores e eficientes para avaliação da proteção
- **Tamanho do Contexto**: Mantenha o contexto de referência conciso, mas abrangente
- **Cache**: Considere armazenar resultados de validação para conteúdos repetidos
## Solução de Problemas
<Accordion title="Validação Sempre Falha">
**Possíveis Causas:**
- Contexto muito restrito ou não relacionado à saída da tarefa
- Limiar configurado alto demais para o tipo de conteúdo
- Contexto de referência desatualizado
**Soluções:**
- Revise e atualize o contexto para corresponder aos requisitos da tarefa
- Reduza o limiar ou utilize validação padrão baseada em veredito
- Certifique-se de que o contexto esteja atual e correto
</Accordion>
<Accordion title="Falsos Positivos (Conteúdo Válido Marcado como Inválido)">
**Possíveis Causas:**
- Limiar alto demais para tarefas criativas ou interpretativas
- Contexto não cobre todos os aspectos válidos da saída
- Modelo de avaliação excessivamente conservador
**Soluções:**
- Reduza o limiar ou utilize validação padrão
- Expanda o contexto para incluir um espectro maior do conteúdo aceitável
- Teste com diferentes modelos de avaliação
</Accordion>
<Accordion title="Erros de Avaliação">
**Possíveis Causas:**
- Problemas de conexão de rede
- Modelo LLM indisponível ou com limite de uso
- Saída ou contexto da tarefa em formato inadequado
**Soluções:**
- Verifique a conectividade de rede e o status do serviço LLM
- Implemente lógica de retentativas para falhas transitórias
- Valide o formato da saída da tarefa antes da avaliação da proteção
</Accordion>
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nosso suporte para assistência na configuração ou solução de problemas da proteção contra alucinações.
</Card>

179
docs/pt-BR/enterprise/features/integrations.mdx Normal file
View File

@@ -0,0 +1,179 @@
---
title: Integrações
description: "Aplicativos conectados para que seus agentes possam tomar ações."
icon: "plug"
---
## Visão Geral
Permita que seus agentes autentiquem com qualquer provedor habilitado para OAuth e tomem ações. Do Salesforce e HubSpot ao Google e GitHub, você conta com mais de 16 serviços integrados.
<Frame>
![Integrações](/images/enterprise/crew_connectors.png)
</Frame>
## Integrações Suportadas
### **Comunicação & Colaboração**
- **Gmail** - Gerencie e-mails e rascunhos
- **Slack** - Notificações e alertas do workspace
- **Microsoft** - Integração com Office 365 e Teams
### **Gerenciamento de Projetos**
- **Jira** - Rastreamento de issues e gerenciamento de projetos
- **ClickUp** - Gerenciamento de tarefas e produtividade
- **Asana** - Coordenação de tarefas e projetos de equipe
- **Notion** - Gerenciamento de páginas e bases de dados
- **Linear** - Gerenciamento de projetos de software e bugs
- **GitHub** - Gerenciamento de repositórios e issues
### **Gestão de Relacionamento com o Cliente**
- **Salesforce** - Gerenciamento de contas e oportunidades de CRM
- **HubSpot** - Gestão de pipeline de vendas e contatos
- **Zendesk** - Administração de chamados de suporte ao cliente
### **Negócios & Finanças**
- **Stripe** - Processamento de pagamentos e gerenciamento de clientes
- **Shopify** - Gestão de loja de e-commerce e produtos
### **Produtividade & Armazenamento**
- **Google Sheets** - Sincronização de dados de planilhas
- **Google Calendar** - Gerenciamento de eventos e agendas
- **Box** - Armazenamento de arquivos e gerenciamento de documentos
e mais estão por vir!
## Pré-requisitos
Antes de usar as Integrações de Autenticação, certifique-se de que você possui:
- Uma conta [CrewAI Enterprise](https://app.crewai.com). Você pode começar com uma avaliação gratuita.
## Configurando Integrações
### 1. Conecte sua Conta
1. Acesse o [CrewAI Enterprise](https://app.crewai.com)
2. Vá até a aba **Integrações** - https://app.crewai.com/crewai_plus/connectors
3. Clique em **Conectar** no serviço desejado na seção Integrações de Autenticação
4. Complete o fluxo de autenticação OAuth
5. Conceda as permissões necessárias para seu caso de uso
6. Obtenha seu Token Enterprise na sua página de conta do [CrewAI Enterprise](https://app.crewai.com) - https://app.crewai.com/crewai_plus/settings/account
<Frame>
![Integrações](/images/enterprise/enterprise_action_auth_token.png)
</Frame>
### 2. Instale as Ferramentas de Integração
Tudo o que você precisa é da versão mais recente do pacote `crewai-tools`.
```bash
uv add crewai-tools
```
## Exemplos de Uso
### Uso Básico
<Tip>
Todos os serviços nos quais você estiver autenticado estarão disponíveis como ferramentas. Portanto, tudo que você precisa fazer é adicionar o `CrewaiEnterpriseTools` ao seu agente e pronto.
</Tip>
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Obtenha ferramentas enterprise (a ferramenta Gmail será incluída)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# imprima as ferramentas
print(enterprise_tools)
# Crie um agente com capacidades do Gmail
email_agent = Agent(
role="Email Manager",
goal="Manage and organize email communications",
backstory="An AI assistant specialized in email management and communication.",
tools=enterprise_tools
)
# Tarefa para enviar um e-mail
email_task = Task(
description="Draft and send a follow-up email to john@example.com about the project update",
agent=email_agent,
expected_output="Confirmation that email was sent successfully"
)
# Execute a tarefa
crew = Crew(
agents=[email_agent],
tasks=[email_task]
)
# Execute o crew
crew.kickoff()
```
### Filtrando Ferramentas
```python
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
actions_list=["gmail_find_email"] # apenas a ferramenta gmail_find_email estará disponível
)
gmail_tool = enterprise_tools["gmail_find_email"]
gmail_agent = Agent(
role="Gmail Manager",
goal="Manage gmail communications and notifications",
backstory="An AI assistant that helps coordinate gmail communications.",
tools=[gmail_tool]
)
notification_task = Task(
description="Find the email from john@example.com",
agent=gmail_agent,
expected_output="Email found from john@example.com"
)
# Execute a tarefa
crew = Crew(
agents=[slack_agent],
tasks=[notification_task]
)
```
## Melhores Práticas
### Segurança
- **Princípio do Menor Privilégio**: Conceda apenas as permissões mínimas exigidas para as tarefas dos seus agentes
- **Auditorias Regulares**: Revise periodicamente as integrações conectadas e suas permissões
- **Credenciais Seguras**: Nunca insira credenciais diretamente no código; utilize o fluxo seguro de autenticação do CrewAI
### Filtrando Ferramentas
Em um crew implantado, você pode especificar quais ações estão disponíveis para cada integração a partir da página de configurações do serviço ao qual você se conectou.
<Frame>
![Integrações](/images/enterprise/filtering_enterprise_action_tools.png)
</Frame>
### Implantações com Escopo para organizações multiusuário
Você pode implantar seu crew e associar cada integração a um usuário específico. Por exemplo, um crew que se conecta ao Google pode usar a conta do Gmail de um usuário específico.
<Tip>
Isso é útil para organizações multiusuário, onde você deseja direcionar a integração para um usuário específico.
</Tip>
Use o `user_bearer_token` para direcionar a integração a um usuário específico; assim, quando o crew for iniciado, ele usará o bearer token desse usuário para autenticar com a integração. Se o usuário não estiver logado, o crew não utilizará nenhuma integração conectada. Use o bearer token padrão para autenticar com as integrações que estão sendo implantadas com o crew.
<Frame>
![Integrações](/images/enterprise/user_bearer_token.png)
</Frame>
### Precisa de Ajuda?
<Card title="Precisa de ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nosso time de suporte para assistência com a configuração de integrações ou solução de problemas.
</Card>

107
docs/pt-BR/enterprise/features/tool-repository.mdx Normal file
View File

@@ -0,0 +1,107 @@
---
title: Repositório de Ferramentas
description: "Usando o Repositório de Ferramentas para gerenciar suas ferramentas"
icon: "toolbox"
---
## Visão geral
O Repositório de Ferramentas é um gerenciador de pacotes para ferramentas da CrewAI. Ele permite que usuários publiquem, instalem e gerenciem ferramentas que se integram com crews e flows da CrewAI.
As ferramentas podem ser:
- **Privadas**: acessíveis apenas dentro da sua organização (padrão)
- **Públicas**: acessíveis a todos os usuários CrewAI se publicadas com a flag `--public`
O repositório não é um sistema de controle de versões. Use o Git para rastrear mudanças no código e permitir colaboração.
## Pré-requisitos
Antes de usar o Repositório de Ferramentas, certifique-se de que você possui:
- Uma conta [CrewAI Enterprise](https://app.crewai.com)
- [CrewAI CLI](https://docs.crewai.com/concepts/cli#cli) instalada
- uv>=0.5.0 instalado. Veja [como atualizar](https://docs.astral.sh/uv/getting-started/installation/#upgrading-uv)
- [Git](https://git-scm.com) instalado e configurado
- Permissões de acesso para publicar ou instalar ferramentas em sua organização CrewAI Enterprise
## Instalando ferramentas
Para instalar uma ferramenta:
```bash
crewai tool install <tool-name>
```
Isso instala a ferramenta e a adiciona ao `pyproject.toml`.
## Criando e publicando ferramentas
Para criar um novo projeto de ferramenta:
```bash
crewai tool create <tool-name>
```
Isso gera um projeto de ferramenta estruturado localmente.
Após fazer alterações, inicialize um repositório Git e faça o commit do código:
```bash
git init
git add .
git commit -m "Initial version"
```
Para publicar a ferramenta:
```bash
crewai tool publish
```
Por padrão, as ferramentas são publicadas como privadas. Para tornar uma ferramenta pública:
```bash
crewai tool publish --public
```
Para mais detalhes sobre como construir ferramentas, acesse [Criando suas próprias ferramentas](https://docs.crewai.com/concepts/tools#creating-your-own-tools).
## Atualizando ferramentas
Para atualizar uma ferramenta publicada:
1. Modifique a ferramenta localmente
2. Atualize a versão no `pyproject.toml` (por exemplo, de `0.1.0` para `0.1.1`)
3. Faça o commit das alterações e publique
```bash
git commit -m "Update version to 0.1.1"
crewai tool publish
```
## Excluindo ferramentas
Para excluir uma ferramenta:
1. Acesse o [CrewAI Enterprise](https://app.crewai.com)
2. Navegue até **Ferramentas**
3. Selecione a ferramenta
4. Clique em **Excluir**
<Warning>
A exclusão é permanente. Ferramentas excluídas não podem ser restauradas ou reinstaladas.
</Warning>
## Verificações de segurança
Cada versão publicada passa por verificações automáticas de segurança e só fica disponível para instalação após aprovação.
Você pode verificar o status das verificações de segurança de uma ferramenta em:
`CrewAI Enterprise > Tools > Your Tool > Versions`
<Card title="Precisa de ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para assistência com integração de API ou resolução de problemas.
</Card>

146
docs/pt-BR/enterprise/features/traces.mdx Normal file
View File

@@ -0,0 +1,146 @@
---
title: Traces
description: "Usando Traces para monitorar seus Crews"
icon: "timeline"
---
## Visão Geral
Traces fornecem visibilidade abrangente sobre as execuções dos seus crews, ajudando você a monitorar o desempenho, depurar problemas e otimizar os fluxos de trabalho dos seus agentes de IA.
## O que são Traces?
Traces no CrewAI Enterprise são registros detalhados de execução que capturam todos os aspectos da operação do seu crew, desde as entradas iniciais até as saídas finais. Eles registram:
- Pensamentos e raciocínio do agente
- Detalhes da execução das tarefas
- Uso de ferramentas e resultados
- Métricas de consumo de tokens
- Tempos de execução
- Estimativas de custo
<Frame>
![Traces Overview](/images/enterprise/traces-overview.png)
</Frame>
## Acessando os Traces
<Steps>
<Step title="Navegue até a aba Traces">
No seu painel do CrewAI Enterprise, clique em **Traces** para ver todos os registros de execução.
</Step>
<Step title="Selecione uma Execução">
Você verá uma lista de todas as execuções do crew, ordenadas por data. Clique em qualquer execução para visualizar seu trace detalhado.
</Step>
</Steps>
## Entendendo a Interface do Trace
A interface do trace é dividida em várias seções, cada uma fornecendo diferentes insights sobre a execução do seu crew:
### 1. Resumo da Execução
A seção superior exibe métricas de alto nível sobre a execução:
- **Total de Tokens**: Número de tokens consumidos em todas as tarefas
- **Prompt Tokens**: Tokens usados em prompts para o LLM
- **Completion Tokens**: Tokens gerados nas respostas do LLM
- **Requisições**: Número de chamadas de API feitas
- **Tempo de Execução**: Duração total da execução do crew
- **Custo Estimado**: Custo aproximado com base no uso de tokens
<Frame>
![Execution Summary](/images/enterprise/trace-summary.png)
</Frame>
### 2. Tarefas & Agentes
Esta seção mostra todas as tarefas e agentes que fizeram parte da execução do crew:
- Nome da tarefa e atribuição do agente
- Agentes e LLMs usados em cada tarefa
- Status (concluído/falhou)
- Tempo de execução individual da tarefa
<Frame>
![Task List](/images/enterprise/trace-tasks.png)
</Frame>
### 3. Saída Final
Exibe o resultado final produzido pelo crew após a conclusão de todas as tarefas.
<Frame>
![Final Output](/images/enterprise/final-output.png)
</Frame>
### 4. Linha do Tempo da Execução
Uma representação visual de quando cada tarefa começou e terminou, ajudando a identificar gargalos ou padrões de execução paralela.
<Frame>
![Execution Timeline](/images/enterprise/trace-timeline.png)
</Frame>
### 5. Visão Detalhada da Tarefa
Ao clicar em uma tarefa específica na linha do tempo ou na lista de tarefas, você verá:
<Frame>
![Detailed Task View](/images/enterprise/trace-detailed-task.png)
</Frame>
- **Task Key**: Identificador único da tarefa
- **Task ID**: Identificador técnico no sistema
- **Status**: Estado atual (concluída/em execução/falhou)
- **Agente**: Qual agente executou a tarefa
- **LLM**: Modelo de linguagem usado nesta tarefa
- **Início/Fim**: Quando a tarefa foi iniciada e concluída
- **Tempo de Execução**: Duração desta tarefa específica
- **Descrição da Tarefa**: O que o agente foi instruído a fazer
- **Expected Output**: Qual formato de saída foi solicitado
- **Input**: Qualquer entrada fornecida a essa tarefa vinda de tarefas anteriores
- **Output**: O resultado real produzido pelo agente
## Usando Traces para Depuração
Traces são indispensáveis para solucionar problemas nos seus crews:
<Steps>
<Step title="Identifique Pontos de Falha">
Quando uma execução de crew não produzir os resultados esperados, examine o trace para encontrar onde ocorreu o problema. Procure por:
- Tarefas que falharam
- Decisões inesperadas dos agentes
- Erros no uso de ferramentas
- Instruções mal interpretadas
<Frame>
![Failure Points](/images/enterprise/failure.png)
</Frame>
</Step>
<Step title="Otimizar Desempenho">
Use métricas de execução para identificar gargalos de desempenho:
- Tarefas que demoraram mais do que o esperado
- Uso excessivo de tokens
- Operações redundantes de ferramentas
- Chamadas de API desnecessárias
</Step>
<Step title="Melhore a Eficiência de Custos">
Analise o uso de tokens e as estimativas de custo para otimizar a eficiência do seu crew:
- Considere usar modelos menores para tarefas mais simples
- Refine prompts para serem mais concisos
- Faça cache de informações acessadas frequentemente
- Estruture tarefas para minimizar operações redundantes
</Step>
</Steps>
<Card title="Precisa de ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para assistência com análise de traces ou outros recursos do CrewAI Enterprise.
</Card>

81
docs/pt-BR/enterprise/features/webhook-streaming.mdx Normal file
View File

@@ -0,0 +1,81 @@
---
title: Webhook Streaming
description: "Usando Webhook Streaming para transmitir eventos para o seu webhook"
icon: "webhook"
---
## Visão Geral
O Enterprise Event Streaming permite que você receba atualizações em tempo real via webhook sobre suas crews e flows implantados no CrewAI Enterprise, como chamadas de modelo, uso de ferramentas e etapas do flow.
## Uso
Ao utilizar a API Kickoff, inclua um objeto `webhooks` em sua requisição, por exemplo:
```json
{
"inputs": {"foo": "bar"},
"webhooks": {
"events": ["crew_kickoff_started", "llm_call_started"],
"url": "https://your.endpoint/webhook",
"realtime": false,
"authentication": {
"strategy": "bearer",
"token": "my-secret-token"
}
}
}
```
Se `realtime` estiver definido como `true`, cada evento será entregue individualmente e imediatamente, com impacto no desempenho da crew/flow.
## Formato do Webhook
Cada webhook envia uma lista de eventos:
```json
{
"events": [
{
"id": "event-id",
"execution_id": "crew-run-id",
"timestamp": "2025-02-16T10:58:44.965Z",
"type": "llm_call_started",
"data": {
"model": "gpt-4",
"messages": [
{"role": "system", "content": "You are an assistant."},
{"role": "user", "content": "Summarize this article."}
]
}
}
]
}
```
A estrutura do objeto `data` varia conforme o tipo de evento. Consulte a [lista de eventos](https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events) no GitHub.
Como as requisições são enviadas via HTTP, a ordem dos eventos não pode ser garantida. Caso precise de ordenação, utilize o campo `timestamp`.
## Eventos Suportados
O CrewAI oferece suporte a eventos do sistema e eventos personalizados no Enterprise Event Streaming. Esses eventos são enviados para o endpoint do seu webhook configurado durante a execução das crews e flows.
- `crew_kickoff_started`
- `crew_step_started`
- `crew_step_completed`
- `crew_execution_completed`
- `llm_call_started`
- `llm_call_completed`
- `tool_usage_started`
- `tool_usage_completed`
- `crew_test_failed`
- *...e outros*
Os nomes dos eventos correspondem ao event bus interno. Veja o [código fonte no GitHub](https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events) para a lista completa.
Você pode emitir seus próprios eventos personalizados, e eles serão entregues através do webhook stream juntamente com os eventos do sistema.
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para assistência com integração de webhook ou solução de problemas.
</Card>

51
docs/pt-BR/enterprise/guides/azure-openai-setup.mdx Normal file
View File

@@ -0,0 +1,51 @@
---
title: "Configuração do Azure OpenAI"
description: "Configure o Azure OpenAI com o Crew Studio para conexões empresariais de LLM"
icon: "microsoft"
---
Este guia orienta você na conexão do Azure OpenAI com o Crew Studio para operações de IA empresarial sem interrupções.
## Processo de Configuração
<Steps>
<Step title="Acesse o Azure OpenAI Studio">
1. No Azure, vá para `Serviços de IA do Azure > selecione sua implantação > abra o Azure OpenAI Studio`.
2. No menu à esquerda, clique em `Implantações`. Se não houver nenhuma, crie uma implantação com o modelo desejado.
3. Uma vez criada, selecione sua implantação e localize o `Target URI` e a `Key` no lado direito da página. Mantenha esta página aberta, pois você precisará dessas informações.
<Frame>
<img src="/images/enterprise/azure-openai-studio.png" alt="Azure OpenAI Studio" />
</Frame>
</Step>
<Step title="Configure a Conexão Enterprise do CrewAI">
4. Em outra aba, abra `CrewAI Enterprise > LLM Connections`. Dê um nome à sua LLM Connection, selecione Azure como provedor e escolha o mesmo modelo que você selecionou no Azure.
5. Na mesma página, adicione as variáveis de ambiente do passo 3:
- Uma chamada `AZURE_DEPLOYMENT_TARGET_URL` (usando o Target URI). A URL deve ser parecida com: https://your-deployment.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview
- Outra chamada `AZURE_API_KEY` (usando a Key).
6. Clique em `Add Connection` para salvar sua LLM Connection.
</Step>
<Step title="Defina Configurações Padrão">
7. Em `CrewAI Enterprise > Settings > Defaults > Crew Studio LLM Settings`, defina a nova LLM Connection e o modelo como padrão.
</Step>
<Step title="Configure o Acesso à Rede">
8. Certifique-se das configurações de acesso à rede:
- No Azure, vá para `Azure OpenAI > selecione sua implantação`.
- Navegue até `Resource Management > Networking`.
- Certifique-se de que a opção `Allow access from all networks` está habilitada. Se essa configuração estiver restrita, o CrewAI pode ser impedido de acessar seu endpoint do Azure OpenAI.
</Step>
</Steps>
## Verificação
Tudo pronto! O Crew Studio agora utilizará sua conexão Azure OpenAI. Teste a conexão criando um crew ou task simples para garantir que tudo está funcionando corretamente.
## Solução de Problemas
Se você encontrar problemas:
- Verifique se o formato do Target URI corresponde ao padrão esperado
- Confira se a API key está correta e com as permissões adequadas
- Certifique-se de que o acesso à rede está configurado para permitir conexões do CrewAI
- Confirme se o modelo da implantação corresponde ao que você configurou no CrewAI

43
docs/pt-BR/enterprise/guides/build-crew.mdx Normal file
View File

@@ -0,0 +1,43 @@
---
title: "Build Crew"
description: "Uma Crew é um grupo de agentes que trabalham juntos para completar uma tarefa."
icon: "people-arrows"
---
## Visão Geral
[CrewAI Enterprise](https://app.crewai.com) simplifica o processo de **criação**, **implantação** e **gerenciamento** dos seus agentes de IA em ambientes de produção.
## Primeiros Passos
<iframe
width="100%"
height="400"
src="https://www.youtube.com/embed/-kSOTtYzgEw"
title="Building Crews with CrewAI CLI"
frameborder="0"
style={{ borderRadius: '10px' }}
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
### Instalação e Configuração
<Card title="Siga a Instalação Padrão" icon="wrench" href="/pt-BR/installation">
Siga nosso guia de instalação padrão para configurar o CrewAI CLI e criar seu primeiro projeto.
</Card>
### Construindo Sua Crew
<Card title="Tutorial Rápido" icon="rocket" href="/pt-BR/quickstart">
Siga nosso tutorial rápido para criar sua primeira crew de agentes usando a configuração YAML.
</Card>
## Suporte e Recursos
Para suporte ou dúvidas específicas da versão Enterprise, entre em contato com nossa equipe dedicada através do [support@crewai.com](mailto:support@crewai.com).
<Card title="Agende uma Demonstração" icon="calendar" href="mailto:support@crewai.com">
Reserve um horário com nossa equipe para saber mais sobre os recursos Enterprise e como eles podem beneficiar sua organização.
</Card>

293
docs/pt-BR/enterprise/guides/deploy-crew.mdx Normal file
View File

@@ -0,0 +1,293 @@
---
title: "Deploy Crew"
description: "Implantando um Crew na CrewAI Enterprise"
icon: "rocket"
---
<Note>
Depois de criar um crew localmente ou pelo Crew Studio, o próximo passo é implantá-lo na plataforma CrewAI Enterprise. Este guia cobre múltiplos métodos de implantação para ajudá-lo a escolher a melhor abordagem para o seu fluxo de trabalho.
</Note>
## Pré-requisitos
<CardGroup cols={2}>
<Card title="Crew Pronto para Implantação" icon="users">
Você deve ter um crew funcional, criado localmente ou pelo Crew Studio
</Card>
<Card title="Repositório GitHub" icon="github">
O código do seu crew deve estar em um repositório do GitHub (para o método de integração com GitHub)
</Card>
</CardGroup>
## Opção 1: Implantar Usando o CrewAI CLI
A CLI fornece a maneira mais rápida de implantar crews desenvolvidos localmente na plataforma Enterprise.
<Steps>
<Step title="Instale o CrewAI CLI">
Se ainda não tiver, instale o CrewAI CLI:
```bash
pip install crewai[tools]
```
<Tip>
A CLI vem com o pacote principal CrewAI, mas o extra `[tools]` garante todas as dependências de implantação.
</Tip>
</Step>
<Step title="Autentique-se na Plataforma Enterprise">
Primeiro, você precisa autenticar sua CLI com a plataforma CrewAI Enterprise:
```bash
# Se já possui uma conta CrewAI Enterprise
crewai login
# Se vai criar uma nova conta
crewai signup
```
Ao executar qualquer um dos comandos, a CLI irá:
1. Exibir uma URL e um código de dispositivo único
2. Abrir seu navegador para a página de autenticação
3. Solicitar a confirmação do dispositivo
4. Completar o processo de autenticação
Após a autenticação bem-sucedida, você verá uma mensagem de confirmação no terminal!
</Step>
<Step title="Criar uma Implantação">
No diretório do seu projeto, execute:
```bash
crewai deploy create
```
Este comando irá:
1. Detectar informações do seu repositório GitHub
2. Identificar variáveis de ambiente no seu arquivo `.env` local
3. Transferir essas variáveis com segurança para a plataforma Enterprise
4. Criar uma nova implantação com um identificador único
Com a criação bem-sucedida, você verá uma mensagem como:
```shell
Deployment created successfully!
Name: your_project_name
Deployment ID: 01234567-89ab-cdef-0123-456789abcdef
Current Status: Deploy Enqueued
```
</Step>
<Step title="Acompanhe o Progresso da Implantação">
Acompanhe o status da implantação com:
```bash
crewai deploy status
```
Para ver logs detalhados do processo de build:
```bash
crewai deploy logs
```
<Tip>
A primeira implantação normalmente leva de 10 a 15 minutos, pois as imagens dos containers são construídas. As próximas implantações são bem mais rápidas.
</Tip>
</Step>
</Steps>
## Comandos Adicionais da CLI
O CrewAI CLI oferece vários comandos para gerenciar suas implantações:
```bash
# Liste todas as suas implantações
crewai deploy list
# Consulte o status de uma implantação
crewai deploy status
# Veja os logs da implantação
crewai deploy logs
# Envie atualizações após alterações no código
crewai deploy push
# Remova uma implantação
crewai deploy remove <deployment_id>
```
## Opção 2: Implantar Diretamente pela Interface Web
Você também pode implantar seus crews diretamente pela interface web da CrewAI Enterprise conectando sua conta do GitHub. Esta abordagem não requer utilizar a CLI na sua máquina local.
<Steps>
<Step title="Enviar no GitHub">
Você precisa subir seu crew para um repositório do GitHub. Caso ainda não tenha criado um crew, você pode [seguir este tutorial](/pt-BR/quickstart).
</Step>
<Step title="Conectando o GitHub ao CrewAI Enterprise">
1. Faça login em [CrewAI Enterprise](https://app.crewai.com)
2. Clique no botão "Connect GitHub"
<Frame>
![Botão Connect GitHub](/images/enterprise/connect-github.png)
</Frame>
</Step>
<Step title="Selecionar o Repositório">
Após conectar sua conta GitHub, você poderá selecionar qual repositório deseja implantar:
<Frame>
![Selecionar Repositório](/images/enterprise/select-repo.png)
</Frame>
</Step>
<Step title="Definir as Variáveis de Ambiente">
Antes de implantar, você precisará configurar as variáveis de ambiente para conectar ao seu provedor de LLM ou outros serviços:
1. Você pode adicionar variáveis individualmente ou em lote
2. Digite suas variáveis no formato `KEY=VALUE` (uma por linha)
<Frame>
![Definir Variáveis de Ambiente](/images/enterprise/set-env-variables.png)
</Frame>
</Step>
<Step title="Implante Seu Crew">
1. Clique no botão "Deploy" para iniciar o processo de implantação
2. Você pode monitorar o progresso pela barra de progresso
3. A primeira implantação geralmente demora de 10 a 15 minutos; as próximas serão mais rápidas
<Frame>
![Progresso da Implantação](/images/enterprise/deploy-progress.png)
</Frame>
Após a conclusão, você verá:
- A URL exclusiva do seu crew
- Um Bearer token para proteger sua API crew
- Um botão "Delete" caso precise remover a implantação
</Step>
</Steps>
## ⚠️ Requisitos de Segurança para Variáveis de Ambiente
<Warning>
**Importante**: A CrewAI Enterprise possui restrições de segurança sobre os nomes de variáveis de ambiente que podem causar falha na implantação caso não sejam seguidas.
</Warning>
### Padrões de Variáveis de Ambiente Bloqueados
Por motivos de segurança, os seguintes padrões de nome de variável de ambiente são **automaticamente filtrados** e causarão problemas de implantação:
**Padrões Bloqueados:**
- Variáveis terminando em `_TOKEN` (ex: `MY_API_TOKEN`)
- Variáveis terminando em `_PASSWORD` (ex: `DB_PASSWORD`)
- Variáveis terminando em `_SECRET` (ex: `API_SECRET`)
- Variáveis terminando em `_KEY` em certos contextos
**Variáveis Bloqueadas Específicas:**
- `GITHUB_USER`, `GITHUB_TOKEN`
- `AWS_REGION`, `AWS_DEFAULT_REGION`
- Diversas variáveis internas do sistema CrewAI
### Exceções Permitidas
Algumas variáveis são explicitamente permitidas mesmo coincidindo com os padrões bloqueados:
- `AZURE_AD_TOKEN`
- `AZURE_OPENAI_AD_TOKEN`
- `ENTERPRISE_ACTION_TOKEN`
- `CREWAI_ENTEPRISE_TOOLS_TOKEN`
### Como Corrigir Problemas de Nomeação
Se sua implantação falhar devido a restrições de variáveis de ambiente:
```bash
# ❌ Estas irão causar falhas na implantação
OPENAI_TOKEN=sk-...
DATABASE_PASSWORD=mysenha
API_SECRET=segredo123
# ✅ Utilize estes padrões de nomeação
OPENAI_API_KEY=sk-...
DATABASE_CREDENTIALS=mysenha
API_CONFIG=segredo123
```
### Melhores Práticas
1. **Use convenções padrão de nomenclatura**: `PROVIDER_API_KEY` em vez de `PROVIDER_TOKEN`
2. **Teste localmente primeiro**: Certifique-se de que seu crew funciona com as variáveis renomeadas
3. **Atualize seu código**: Altere todas as referências aos nomes antigos das variáveis
4. **Documente as mudanças**: Mantenha registro das variáveis renomeadas para seu time
<Tip>
Se você se deparar com falhas de implantação com erros enigmáticos de variáveis de ambiente, confira primeiro os nomes das variáveis em relação a esses padrões.
</Tip>
### Interaja com Seu Crew Implantado
Após a implantação, você pode acessar seu crew por meio de:
1. **REST API**: A plataforma gera um endpoint HTTPS exclusivo com estas rotas principais:
- `/inputs`: Lista os parâmetros de entrada requeridos
- `/kickoff`: Inicia uma execução com os inputs fornecidos
- `/status/{kickoff_id}`: Consulta o status da execução
2. **Interface Web**: Acesse [app.crewai.com](https://app.crewai.com) para visualizar:
- **Aba Status**: Informações da implantação, detalhes do endpoint da API e token de autenticação
- **Aba Run**: Visualização da estrutura do seu crew
- **Aba Executions**: Histórico de todas as execuções
- **Aba Metrics**: Análises de desempenho
- **Aba Traces**: Insights detalhados das execuções
### Dispare uma Execução
No dashboard Enterprise, você pode:
1. Clicar no nome do seu crew para abrir seus detalhes
2. Selecionar "Trigger Crew" na interface de gerenciamento
3. Inserir os inputs necessários no modal exibido
4. Monitorar o progresso à medida que a execução avança pelo pipeline
### Monitoramento e Análises
A plataforma Enterprise oferece recursos abrangentes de observabilidade:
- **Gestão das Execuções**: Acompanhe execuções ativas e concluídas
- **Traces**: Quebra detalhada de cada execução
- **Métricas**: Uso de tokens, tempos de execução e custos
- **Visualização em Linha do Tempo**: Representação visual das sequências de tarefas
### Funcionalidades Avançadas
A plataforma Enterprise também oferece:
- **Gerenciamento de Variáveis de Ambiente**: Armazene e gerencie com segurança as chaves de API
- **Conexões com LLM**: Configure integrações com diversos provedores de LLM
- **Repositório Custom Tools**: Crie, compartilhe e instale ferramentas
- **Crew Studio**: Monte crews via interface de chat sem escrever código
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para ajuda com questões de implantação ou dúvidas sobre a plataforma Enterprise.
</Card>

165
docs/pt-BR/enterprise/guides/enable-crew-studio.mdx Normal file
View File

@@ -0,0 +1,165 @@
---
title: "Ativar Crew Studio"
description: "Ativando o Crew Studio no CrewAI Enterprise"
icon: "comments"
---
<Tip>
Crew Studio é uma poderosa ferramenta **no-code/low-code** que permite criar ou estruturar Crews rapidamente por meio de uma interface conversacional.
</Tip>
## O que é o Crew Studio?
O Crew Studio é uma forma inovadora de criar equipes de agentes de IA sem escrever código.
<Frame>
![Crew Studio Interface](/images/enterprise/crew-studio-interface.png)
</Frame>
Com o Crew Studio, você pode:
- Conversar com o Crew Assistant para descrever seu problema
- Gerar automaticamente agentes e tarefas
- Selecionar as ferramentas apropriadas
- Configurar os inputs necessários
- Gerar código para download e personalização
- Fazer deploy diretamente na plataforma CrewAI Enterprise
## Etapas de Configuração
Antes de começar a usar o Crew Studio, você precisa configurar suas conexões LLM:
<Steps>
<Step title="Configurar a Conexão LLM">
Acesse a aba **LLM Connections** no painel do CrewAI Enterprise e crie uma nova conexão LLM.
<Note>
Sinta-se à vontade para utilizar qualquer provedor LLM suportado pelo CrewAI.
</Note>
Configure sua conexão LLM:
- Insira um `Connection Name` (por exemplo, `OpenAI`)
- Selecione o provedor do modelo: `openai` ou `azure`
- Selecione os modelos que deseja usar em suas Crews geradas pelo Studio
- Recomendamos pelo menos `gpt-4o`, `o1-mini` e `gpt-4o-mini`
- Adicione sua chave de API como uma variável de ambiente:
- Para OpenAI: adicione `OPENAI_API_KEY` com sua chave de API
- Para Azure OpenAI: consulte [este artigo](https://blog.crewai.com/configuring-azure-openai-with-crewai-a-comprehensive-guide/) para detalhes de configuração
- Clique em `Add Connection` para salvar sua configuração
<Frame>
![LLM Connection Configuration](/images/enterprise/llm-connection-config.png)
</Frame>
</Step>
<Step title="Verificar Conexão Adicionada">
Assim que concluir a configuração, você verá sua nova conexão adicionada à lista de conexões disponíveis.
<Frame>
![Connection Added](/images/enterprise/connection-added.png)
</Frame>
</Step>
<Step title="Configurar Padrões do LLM">
No menu principal, vá em **Settings → Defaults** e configure as opções padrão do LLM:
- Selecione os modelos padrão para agentes e outros componentes
- Defina as configurações padrão para o Crew Studio
Clique em `Save Settings` para aplicar as alterações.
<Frame>
![LLM Defaults Configuration](/images/enterprise/llm-defaults.png)
</Frame>
</Step>
</Steps>
## Usando o Crew Studio
Agora que você configurou sua conexão LLM e os padrões, está pronto para começar a usar o Crew Studio!
<Steps>
<Step title="Acessar o Studio">
Navegue até a seção **Studio** no painel do CrewAI Enterprise.
</Step>
<Step title="Iniciar uma Conversa">
Inicie uma conversa com o Crew Assistant descrevendo o problema que deseja resolver:
```md
I need a crew that can research the latest AI developments and create a summary report.
```
O Crew Assistant fará perguntas de esclarecimento para entender melhor suas necessidades.
</Step>
<Step title="Revisar o Crew Gerado">
Revise a configuração do crew gerado, incluindo:
- Agentes e seus papéis
- Tarefas a serem realizadas
- Inputs necessários
- Ferramentas a serem utilizadas
Esta é sua oportunidade para refinar a configuração antes de prosseguir.
</Step>
<Step title="Fazer Deploy ou Baixar">
Quando estiver satisfeito com a configuração, você pode:
- Baixar o código gerado para personalização local
- Fazer deploy do crew diretamente na plataforma CrewAI Enterprise
- Modificar a configuração e gerar o crew novamente
</Step>
<Step title="Testar seu Crew">
Após o deploy, teste seu crew com inputs de exemplo para garantir que ele funcione conforme esperado.
</Step>
</Steps>
<Tip>
Para melhores resultados, forneça descrições claras e detalhadas do que deseja que seu crew realize. Inclua inputs específicos e outputs esperados em sua descrição.
</Tip>
## Exemplo de Fluxo de Trabalho
Veja um fluxo de trabalho típico para criação de um crew com o Crew Studio:
<Steps>
<Step title="Descreva seu Problema">
Comece descrevendo seu problema:
```md
I need a crew that can analyze financial news and provide investment recommendations
```
</Step>
<Step title="Responder Perguntas">
Responda às perguntas de esclarecimento do Crew Assistant para refinar seus requisitos.
</Step>
<Step title="Revisar o Plano">
Revise o plano do crew gerado, que pode incluir:
- Um Research Agent para coletar notícias financeiras
- Um Analysis Agent para interpretar os dados
- Um Recommendations Agent para fornecer conselhos de investimento
</Step>
<Step title="Aprovar ou Modificar">
Aprove o plano ou solicite alterações, se necessário.
</Step>
<Step title="Baixar ou Fazer Deploy">
Baixe o código para personalização ou faça o deploy diretamente na plataforma.
</Step>
<Step title="Testar e Refinar">
Teste seu crew com inputs de exemplo e faça ajustes conforme necessário.
</Step>
</Steps>
<Card title="Precisa de ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para obter assistência com o Crew Studio ou qualquer outro recurso do CrewAI Enterprise.
</Card>

53
docs/pt-BR/enterprise/guides/hubspot-trigger.mdx Normal file
View File

@@ -0,0 +1,53 @@
---
title: "Gatilho HubSpot"
description: "Acione crews do CrewAI diretamente a partir de Workflows do HubSpot"
icon: "hubspot"
---
Este guia fornece um processo passo a passo para configurar gatilhos do HubSpot para o CrewAI Enterprise, permitindo iniciar crews diretamente a partir de Workflows do HubSpot.
## Pré-requisitos
- Uma conta CrewAI Enterprise
- Uma conta HubSpot com o recurso de [Workflows do HubSpot](https://knowledge.hubspot.com/workflows/create-workflows)
## Etapas de Configuração
<Steps>
<Step title="Conecte sua conta HubSpot com o CrewAI Enterprise">
- Faça login na sua `Conta CrewAI Enterprise > Triggers`
- Selecione `HubSpot` na lista de gatilhos disponíveis
- Escolha a conta HubSpot que deseja conectar ao CrewAI Enterprise
- Siga as instruções na tela para autorizar o acesso do CrewAI Enterprise à sua conta HubSpot
- Uma mensagem de confirmação aparecerá assim que o HubSpot estiver conectado com sucesso ao CrewAI Enterprise
</Step>
<Step title="Crie um Workflow no HubSpot">
- Faça login na sua `Conta HubSpot > Automations > Workflows > New workflow`
- Selecione o tipo de workflow que atende às suas necessidades (por exemplo, Começar do zero)
- No construtor de workflow, clique no ícone de mais (+) para adicionar uma nova ação.
- Escolha `Integrated apps > CrewAI > Kickoff a Crew`.
- Selecione a Crew que deseja iniciar.
- Clique em `Save` para adicionar a ação ao seu workflow
<Frame>
<img src="/images/enterprise/hubspot-workflow-1.png" alt="HubSpot Workflow 1" />
</Frame>
</Step>
<Step title="Use os resultados da Crew com outras ações">
- Após a etapa Kickoff a Crew, clique no ícone de mais (+) para adicionar uma nova ação.
- Por exemplo, para enviar uma notificação de e-mail interna, escolha `Communications > Send internal email notification`
- No campo Body, clique em `Insert data`, selecione `View properties or action outputs from > Action outputs > Crew Result` para incluir dados da Crew no e-mail
<Frame>
<img src="/images/enterprise/hubspot-workflow-2.png" alt="HubSpot Workflow 2" />
</Frame>
- Configure quaisquer ações adicionais necessárias
- Revise as etapas do seu workflow para garantir que tudo está configurado corretamente
- Ative o workflow
<Frame>
<img src="/images/enterprise/hubspot-workflow-3.png" alt="HubSpot Workflow 3" />
</Frame>
</Step>
</Steps>
## Recursos Adicionais
Para informações mais detalhadas sobre as ações disponíveis e opções de personalização, consulte a [Documentação de Workflows do HubSpot](https://knowledge.hubspot.com/workflows/create-workflows).

78
docs/pt-BR/enterprise/guides/human-in-the-loop.mdx Normal file
View File

@@ -0,0 +1,78 @@
---
title: "Workflows HITL"
description: "Aprenda como implementar workflows Human-In-The-Loop no CrewAI para decisões aprimoradas"
icon: "user-check"
---
Human-In-The-Loop (HITL) é uma abordagem poderosa que combina inteligência artificial com expertise humana para aprimorar a tomada de decisão e melhorar os resultados das tarefas. Este guia mostra como implementar HITL dentro do CrewAI.
## Configurando Workflows HITL
<Steps>
<Step title="Configure Sua Tarefa">
Configure sua tarefa com a entrada humana habilitada:
<Frame>
<img src="/images/enterprise/crew-human-input.png" alt="Crew Human Input" />
</Frame>
</Step>
<Step title="Forneça o URL do Webhook">
Ao iniciar seu crew, inclua um URL de webhook para entrada humana:
<Frame>
<img src="/images/enterprise/crew-webhook-url.png" alt="Crew Webhook URL" />
</Frame>
</Step>
<Step title="Receba a Notificação do Webhook">
Assim que o crew concluir a tarefa que requer entrada humana, você receberá uma notificação do webhook contendo:
- **ID de Execução**
- **ID da Tarefa**
- **Saída da Tarefa**
</Step>
<Step title="Revise a Saída da Tarefa">
O sistema irá pausar no estado `Pending Human Input`. Revise cuidadosamente a saída da tarefa.
</Step>
<Step title="Envie o Feedback Humano">
Chame o endpoint de retomada do seu crew com as seguintes informações:
<Frame>
<img src="/images/enterprise/crew-resume-endpoint.png" alt="Crew Resume Endpoint" />
</Frame>
<Warning>
**Impacto do Feedback na Execução da Tarefa**:
É crucial ter cuidado ao fornecer o feedback, pois todo o conteúdo do feedback será incorporado como contexto adicional para as próximas execuções da tarefa.
</Warning>
Isso significa:
- Todas as informações do seu feedback passam a fazer parte do contexto da tarefa.
- Detalhes irrelevantes podem prejudicar a execução.
- Feedbacks concisos e relevantes ajudam a manter o foco e a eficiência da tarefa.
- Sempre revise atentamente seu feedback antes de enviá-lo para garantir que ele contém apenas informações pertinentes que irão guiar positivamente a execução da tarefa.
</Step>
<Step title="Lide com Feedback Negativo">
Se você fornecer um feedback negativo:
- O crew irá tentar executar novamente a tarefa com o contexto adicional do seu feedback.
- Você receberá uma nova notificação de webhook para nova revisão.
- Repita os passos 4-6 até estar satisfeito.
</Step>
<Step title="Continuação da Execução">
Quando você enviar um feedback positivo, a execução prosseguirá para as próximas etapas.
</Step>
</Steps>
## Melhores Práticas
- **Seja Específico**: Forneça feedback claro e acionável que trate diretamente da tarefa em questão
- **Mantenha a Relevância**: Inclua apenas informações que possam ajudar a melhorar a execução da tarefa
- **Seja Ágil**: Responda rapidamente aos prompts HITL para evitar atrasos no workflow
- **Revise Cuidadosamente**: Verifique duas vezes o seu feedback antes de enviá-lo para garantir precisão
## Casos de Uso Comuns
Workflows HITL são particularmente valiosos para:
- Garantia de qualidade e validação
- Cenários de tomada de decisão complexa
- Operações sensíveis ou de alto risco
- Tarefas criativas que exigem julgamento humano
- Revisões de conformidade e regulatórias

185
docs/pt-BR/enterprise/guides/kickoff-crew.mdx Normal file
View File

@@ -0,0 +1,185 @@
---
title: "Kickoff Crew"
description: "Inicie um Crew no CrewAI Enterprise"
icon: "flag-checkered"
---
## Visão Geral
Uma vez que você tenha implantado seu crew na plataforma CrewAI Enterprise, é possível iniciar execuções pela interface web ou pela API. Este guia aborda ambos os métodos.
## Método 1: Usando a Interface Web
### Passo 1: Navegue até seu Crew Implantado
1. Faça login no [CrewAI Enterprise](https://app.crewai.com)
2. Clique no nome do crew na sua lista de projetos
3. Você será direcionado para a página de detalhes do crew
<Frame>
![Crew Dashboard](/images/enterprise/crew-dashboard.png)
</Frame>
### Passo 2: Iniciar Execução
Na página de detalhes do seu crew, você tem duas opções para iniciar uma execução:
#### Opção A: Kickoff Rápido
1. Clique no link `Kickoff` na seção Test Endpoints
2. Insira os parâmetros de entrada necessários para seu crew no editor JSON
3. Clique no botão `Send Request`
<Frame>
![Kickoff Endpoint](/images/enterprise/kickoff-endpoint.png)
</Frame>
#### Opção B: Usando a Interface Visual
1. Clique na aba `Run` na página de detalhes do crew
2. Insira os inputs necessários nos campos do formulário
3. Clique no botão `Run Crew`
<Frame>
![Run Crew](/images/enterprise/run-crew.png)
</Frame>
### Passo 3: Monitorar o Progresso da Execução
Após iniciar a execução:
1. Você receberá uma resposta contendo um `kickoff_id` - **copie este ID**
2. Esse ID é fundamental para o acompanhamento da sua execução
<Frame>
![Copy Task ID](/images/enterprise/copy-task-id.png)
</Frame>
### Passo 4: Verificar o Status da Execução
Para monitorar o andamento da sua execução:
1. Clique no endpoint "Status" na seção Test Endpoints
2. Cole o `kickoff_id` no campo indicado
3. Clique no botão "Get Status"
<Frame>
![Get Status](/images/enterprise/get-status.png)
</Frame>
A resposta de status mostrará:
- Estado atual da execução (`running`, `completed`, etc.)
- Detalhes sobre quais tarefas estão em andamento
- Quaisquer outputs gerados até o momento
### Passo 5: Visualizar Resultados Finais
Quando a execução for concluída:
1. O status mudará para `completed`
2. Você poderá visualizar todos os resultados e outputs da execução
3. Para uma visão mais detalhada, acesse a aba `Executions` na página de detalhes do crew
## Método 2: Usando a API
Você também pode iniciar crews programaticamente usando a REST API do CrewAI Enterprise.
### Autenticação
Todas as requisições à API exigem um bearer token para autenticação:
```bash
curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com
```
Seu bearer token está disponível na aba Status na página de detalhes do seu crew.
### Verificando o Status do Crew
Antes de executar operações, você pode verificar se seu crew está funcionando corretamente:
```bash
curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com
```
Uma resposta de sucesso trará uma mensagem indicando que o crew está operacional:
```
Healthy%
```
### Passo 1: Recuperar Entradas Necessárias
Primeiro, descubra quais entradas seu crew exige:
```bash
curl -X GET \
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
https://your-crew-url.crewai.com/inputs
```
A resposta será um objeto JSON contendo um array de parâmetros de entrada obrigatórios, por exemplo:
```json
{"inputs":["topic","current_year"]}
```
Este exemplo mostra que este crew em particular requer dois inputs: `topic` e `current_year`.
### Passo 2: Iniciar Execução
Inicie a execução fornecendo os inputs obrigatórios:
```bash
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
-d '{"inputs": {"topic": "AI Agent Frameworks", "current_year": "2025"}}' \
https://your-crew-url.crewai.com/kickoff
```
A resposta incluirá um `kickoff_id` que você precisará para o acompanhamento:
```json
{"kickoff_id":"abcd1234-5678-90ef-ghij-klmnopqrstuv"}
```
### Passo 3: Verificar Status da Execução
Acompanhe o progresso da execução usando o kickoff_id:
```bash
curl -X GET \
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv
```
## Gerenciando Execuções
### Execuções de Longa Duração
Para execuções que possam demandar mais tempo:
1. Considere implementar um mecanismo de polling para verificar status periodicamente
2. Utilize webhooks (se disponíveis) para notificação quando a execução for concluída
3. Implemente tratamento de erros para possíveis timeouts
### Contexto da Execução
O contexto da execução inclui:
- Inputs fornecidos no momento do kickoff
- Variáveis de ambiente configuradas durante o deploy
- Qualquer estado mantido entre as tarefas
### Depuração de Execuções com Falha
Se uma execução falhar:
1. Verifique a aba "Executions" para logs detalhados
2. Avalie a aba "Traces" para detalhes passo a passo da execução
3. Procure por respostas LLM e uso de ferramentas nos detalhes do trace
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para obter ajuda com problemas de execução ou dúvidas sobre a plataforma Enterprise.
</Card>

103
docs/pt-BR/enterprise/guides/react-component-export.mdx Normal file
View File

@@ -0,0 +1,103 @@
---
title: "Exportação de Componentes React"
description: "Aprenda como exportar e integrar componentes React do CrewAI Enterprise em suas aplicações"
icon: "react"
---
Este guia explica como exportar crews do CrewAI Enterprise como componentes React e integrá-los às suas próprias aplicações.
## Exportando um Componente React
<Steps>
<Step title="Exporte o Componente">
Clique no menu de opções (três pontos à direita do seu crew implantado), selecione a opção de exportação e salve o arquivo localmente. Usaremos o arquivo `CrewLead.jsx` como exemplo.
<Frame>
<img src="/images/enterprise/export-react-component.png" alt="Exportar Componente React" />
</Frame>
</Step>
</Steps>
## Configurando seu Ambiente React
Para executar este componente React localmente, você precisará configurar um ambiente de desenvolvimento React e integrar este componente em um projeto React.
<Steps>
<Step title="Instale o Node.js">
- Baixe e instale o Node.js no site oficial: https://nodejs.org/
- Escolha a versão LTS (Long Term Support) para maior estabilidade.
</Step>
<Step title="Crie um novo projeto React">
- Abra o Prompt de Comando ou PowerShell
- Navegue até o diretório onde deseja criar seu projeto
- Execute o seguinte comando para criar um novo projeto React:
```bash
npx create-react-app my-crew-app
```
- Entre no diretório do projeto:
```bash
cd my-crew-app
```
</Step>
<Step title="Instale as dependências necessárias">
```bash
npm install react-dom
```
</Step>
<Step title="Crie o componente CrewLead">
- Mova o arquivo baixado `CrewLead.jsx` para a pasta `src` do seu projeto.
</Step>
<Step title="Modifique seu App.js para usar o componente CrewLead">
- Abra o arquivo `src/App.js`
- Substitua o conteúdo por algo semelhante a isso:
```jsx
import React from 'react';
import CrewLead from './CrewLead';
function App() {
return (
<div className="App">
<CrewLead baseUrl="YOUR_API_BASE_URL" bearerToken="YOUR_BEARER_TOKEN" />
</div>
);
}
export default App;
```
- Substitua `YOUR_API_BASE_URL` e `YOUR_BEARER_TOKEN` pelos valores reais da sua API.
</Step>
<Step title="Inicie o servidor de desenvolvimento">
- No diretório do seu projeto, execute:
```bash
npm start
```
- Isso iniciará o servidor de desenvolvimento, e seu navegador padrão será aberto automaticamente em http://localhost:3000, onde você verá sua aplicação React rodando.
</Step>
</Steps>
## Personalização
Você pode então personalizar o `CrewLead.jsx` para adicionar cor, título etc.
<Frame>
<img src="/images/enterprise/customise-react-component.png" alt="Personalizar Componente React" />
</Frame>
<Frame>
<img src="/images/enterprise/customise-react-component-2.png" alt="Personalizar Componente React" />
</Frame>
## Próximos Passos
- Personalize o estilo do componente para combinar com o design da sua aplicação
- Adicione props adicionais para configuração
- Integre com o gerenciamento de estado da sua aplicação
- Adicione tratamento de erros e estados de carregamento

44
docs/pt-BR/enterprise/guides/salesforce-trigger.mdx Normal file
View File

@@ -0,0 +1,44 @@
---
title: "Trigger Salesforce"
description: "Dispare equipes CrewAI a partir de fluxos de trabalho do Salesforce para automação de CRM"
icon: "salesforce"
---
A CrewAI Enterprise pode ser acionada a partir do Salesforce para automatizar fluxos de trabalho de gestão de relacionamento com o cliente e aprimorar suas operações de vendas.
## Visão Geral
O Salesforce é uma das principais plataformas de gestão de relacionamento com o cliente (CRM), que ajuda empresas a otimizar operações de vendas, atendimento e marketing. Ao configurar triggers da CrewAI a partir do Salesforce, você pode:
- Automatizar a classificação e qualificação de leads
- Gerar materiais de vendas personalizados
- Aprimorar o atendimento ao cliente com respostas baseadas em IA
- Otimizar análise e relatórios de dados
## Demonstração
<Frame>
<iframe width="100%" height="400" src="https://www.youtube.com/embed/oJunVqjjfu4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</Frame>
## Primeiros Passos
Para configurar triggers no Salesforce:
1. **Contato com o Suporte**: Entre em contato com o suporte da CrewAI Enterprise para obter assistência na configuração dos triggers no Salesforce
2. **Revisar Requisitos**: Certifique-se de possuir as permissões necessárias no Salesforce e acesso à API
3. **Configurar Conexão**: Trabalhe com a equipe de suporte para estabelecer a conexão entre a CrewAI e sua instância do Salesforce
4. **Testar Triggers**: Verifique se os triggers funcionam corretamente para os seus casos de uso específicos
## Casos de Uso
Cenários comuns de uso de triggers Salesforce + CrewAI incluem:
- **Processamento de Leads**: Analisar e classificar leads recebidos automaticamente
- **Geração de Propostas**: Criar propostas personalizadas com base nos dados das oportunidades
- **Insights de Clientes**: Gerar relatórios de análise a partir do histórico de interações com clientes
- **Automação de Follow-up**: Criar mensagens de follow-up e recomendações personalizadas
## Próximos Passos
Para instruções detalhadas de configuração e opções avançadas, entre em contato com o suporte da CrewAI Enterprise, que pode fornecer orientações personalizadas para o seu ambiente Salesforce e necessidades de negócio.

61
docs/pt-BR/enterprise/guides/slack-trigger.mdx Normal file
View File

@@ -0,0 +1,61 @@
---
title: "Slack Trigger"
description: "Acione crews do CrewAI diretamente do Slack usando comandos de barra"
icon: "slack"
---
Este guia explica como iniciar um crew diretamente do Slack usando triggers do CrewAI.
## Pré-requisitos
- Trigger do CrewAI para Slack instalado e conectado ao seu workspace do Slack
- Pelo menos um crew configurado no CrewAI
## Etapas de Configuração
<Steps>
<Step title="Garanta que o trigger do CrewAI para Slack está configurado">
No dashboard do CrewAI, navegue até a seção **Triggers**.
<Frame>
<img src="/images/enterprise/slack-integration.png" alt="Integração CrewAI Slack" />
</Frame>
Verifique se o Slack está listado e conectado.
</Step>
<Step title="Abra o canal do Slack">
- Navegue até o canal onde você deseja iniciar o crew.
- Digite o comando de barra "**/kickoff**" para iniciar o processo de kickoff do crew.
- Você deverá ver "**Kickoff crew**" aparecendo enquanto digita:
<Frame>
<img src="/images/enterprise/kickoff-slack-crew.png" alt="Kickoff crew" />
</Frame>
- Pressione Enter ou selecione a opção "**Kickoff crew**". Uma caixa de diálogo intitulada "**Kickoff an AI Crew**" aparecerá.
</Step>
<Step title="Selecione o crew que deseja iniciar">
- No menu suspenso rotulado "**Select of the crews online:**", escolha o crew que deseja iniciar.
- No exemplo abaixo, "**prep-for-meeting**" está selecionado:
<Frame>
<img src="/images/enterprise/kickoff-slack-crew-dropdown.png" alt="Kickoff crew dropdown" />
</Frame>
- Se o seu crew exigir algum input, clique no botão "**Add Inputs**" para fornecê-los.
<Note>
O botão "**Add Inputs**" é mostrado no exemplo acima, mas ainda não foi clicado.
</Note>
</Step>
<Step title="Clique em Kickoff e aguarde o término do crew">
- Assim que você tiver selecionado o crew e adicionado os inputs necessários, clique em "**Kickoff**" para iniciar o crew.
<Frame>
<img src="/images/enterprise/kickoff-slack-crew-kickoff.png" alt="Kickoff crew" />
</Frame>
- O crew começará a ser executado e você verá os resultados no canal do Slack.
<Frame>
<img src="/images/enterprise/kickoff-slack-crew-results.png" alt="Kickoff crew results" />
</Frame>
</Step>
</Steps>
## Dicas
- Certifique-se de que você possui as permissões necessárias para usar o comando `/kickoff` em seu workspace do Slack.
- Se você não visualizar o crew desejado no menu suspenso, verifique se ele está devidamente configurado e online no CrewAI.

87
docs/pt-BR/enterprise/guides/team-management.mdx Normal file
View File

@@ -0,0 +1,87 @@
---
title: "Gestão de Equipes"
description: "Aprenda como convidar e gerenciar membros da equipe em sua organização CrewAI Enterprise"
icon: "users"
---
Como administrador de uma conta CrewAI Enterprise, você pode facilmente convidar novos membros para sua organização. Este guia irá orientá-lo passo a passo pelo processo.
## Convidando Membros da Equipe
<Steps>
<Step title="Acesse a Página de Configurações">
- Faça login na sua conta CrewAI Enterprise
- Procure o ícone de engrenagem (⚙️) no canto superior direito do painel
- Clique no ícone de engrenagem para acessar a página de **Configurações**:
<Frame>
<img src="/images/enterprise/settings-page.png" alt="Página de Configurações" />
</Frame>
</Step>
<Step title="Navegue até a Seção de Membros">
- Na página de Configurações, você verá a aba `Members`
- Clique na aba `Members` para acessar a página de **Membros**:
<Frame>
<img src="/images/enterprise/members-tab.png" alt="Aba Membros" />
</Frame>
</Step>
<Step title="Convidar Novos Membros">
- Na seção de Membros, você verá uma lista dos membros atuais (incluindo você)
- Localize o campo de entrada `Email`
- Digite o endereço de e-mail da pessoa que você deseja convidar
- Clique no botão `Invite` para enviar o convite
</Step>
<Step title="Repita Conforme Necessário">
- Você pode repetir esse processo para convidar vários membros da equipe
- Cada membro convidado receberá um convite por e-mail para ingressar na sua organização
</Step>
</Steps>
## Adicionando Funções
Você pode adicionar funções aos membros da equipe para controlar o acesso a diferentes partes da plataforma.
<Steps>
<Step title="Acesse a Página de Configurações">
- Faça login na sua conta CrewAI Enterprise
- Procure o ícone de engrenagem (⚙️) no canto superior direito do painel
- Clique no ícone de engrenagem para acessar a página de **Configurações**:
<Frame>
<img src="/images/enterprise/settings-page.png" alt="Página de Configurações" />
</Frame>
</Step>
<Step title="Navegue até a Seção de Funções">
- Na página de Configurações, você verá a aba `Roles`
- Clique na aba `Roles` para acessar a página de **Funções**.
<Frame>
<img src="/images/enterprise/roles-tab.png" alt="Aba Funções" />
</Frame>
- Clique no botão `Add Role` para adicionar uma nova função.
- Insira os detalhes e as permissões da função e clique no botão `Create Role` para criar a função.
<Frame>
<img src="/images/enterprise/add-role-modal.png" alt="Modal Adicionar Função" />
</Frame>
</Step>
<Step title="Adicionar Funções aos Membros">
- Na seção de Membros, você verá uma lista dos membros atuais (incluindo você)
<Frame>
<img src="/images/enterprise/member-accepted-invitation.png" alt="Membro Aceitou Convite" />
</Frame>
- Após o membro aceitar o convite, você poderá adicionar uma função a ele.
- Volte para a aba `Roles`
- Vá até o membro ao qual deseja adicionar uma função e, na coluna `Role`, clique no menu suspenso
- Selecione a função que deseja atribuir ao membro
- Clique no botão `Update` para salvar a função
<Frame>
<img src="/images/enterprise/assign-role.png" alt="Adicionar Função ao Membro" />
</Frame>
</Step>
</Steps>
## Notas Importantes
- **Privilégios de Administrador**: Apenas usuários com privilégios administrativos podem convidar novos membros
- **Precisão do E-mail**: Certifique-se de que você tem os endereços de e-mail corretos dos membros da equipe
- **Aceite do Convite**: Os membros convidados precisarão aceitar o convite para ingressar na sua organização
- **Notificações por E-mail**: Oriente seus membros a verificarem o e-mail (incluindo a pasta de spam) para localizar o convite
Seguindo estes passos, você conseguirá expandir sua equipe e colaborar de forma mais eficaz dentro da sua organização CrewAI Enterprise.

88
docs/pt-BR/enterprise/guides/update-crew.mdx Normal file
View File

@@ -0,0 +1,88 @@
---
title: "Atualizar Crew"
description: "Atualizando uma Crew no CrewAI Enterprise"
icon: "pencil"
---
<Note>
Após implantar sua crew no CrewAI Enterprise, pode ser necessário fazer atualizações no código, configurações de segurança ou configuração.
Este guia explica como realizar essas operações de atualização comuns.
</Note>
## Por que atualizar sua Crew?
Por padrão, o CrewAI não irá buscar atualizações do GitHub automaticamente, então você precisará acionar manualmente as atualizações, a menos que tenha marcado a opção `Auto-update` ao implantar sua crew.
Há várias razões para querer atualizar sua implantação de crew:
- Você deseja atualizar o código com o commit mais recente que enviou para o GitHub
- Você deseja redefinir o bearer token por motivos de segurança
- Você deseja atualizar variáveis de ambiente
## 1. Atualizando o código da sua Crew para o último commit
Quando você fizer push de novos commits no seu repositório do GitHub e quiser atualizar sua implantação:
1. Navegue até sua crew na plataforma CrewAI Enterprise
2. Clique no botão `Re-deploy` na página de detalhes da sua crew
<Frame>
![Botão Re-deploy](/images/enterprise/redeploy-button.png)
</Frame>
Isso irá acionar uma atualização que pode ser acompanhada pela barra de progresso. O sistema irá buscar o código mais recente do seu repositório e reconstruir sua implantação.
## 2. Redefinindo o Bearer Token
Se precisar gerar um novo bearer token (por exemplo, se suspeitar que o token atual possa ter sido comprometido):
1. Navegue até sua crew na plataforma CrewAI Enterprise
2. Encontre a seção `Bearer Token`
3. Clique no botão `Reset` ao lado do token atual
<Frame>
![Reset Token](/images/enterprise/reset-token.png)
</Frame>
<Warning>
A redefinição do bearer token invalidará imediatamente o token anterior. Certifique-se de atualizar quaisquer aplicações ou scripts que estejam utilizando o token antigo.
</Warning>
## 3. Atualizando Variáveis de Ambiente
Para atualizar as variáveis de ambiente da sua crew:
1. Primeiro, acesse a página de implantação clicando no nome da sua crew
<Frame>
![Botão Variáveis de Ambiente](/images/enterprise/env-vars-button.png)
</Frame>
2. Localize a seção `Environment Variables` (você deverá clicar no ícone de `Settings` para acessá-la)
3. Edite as variáveis existentes ou adicione novas nos campos fornecidos
4. Clique no botão `Update` ao lado de cada variável que você modificar
<Frame>
![Atualizar Variáveis de Ambiente](/images/enterprise/update-env-vars.png)
</Frame>
5. Por fim, clique no botão `Update Deployment` na parte inferior da página para aplicar as alterações
<Note>
A atualização das variáveis de ambiente irá acionar uma nova implantação, mas isso atualizará apenas a configuração de ambiente e não o código em si.
</Note>
## Após atualizar
Após realizar qualquer atualização:
1. O sistema irá reconstruir e reimplantar sua crew
2. Você poderá monitorar o progresso da implantação em tempo real
3. Quando finalizado, teste sua crew para garantir que as alterações estão funcionando como esperado
<Tip>
Se encontrar algum problema após a atualização, é possível visualizar os logs de implantação na plataforma ou entrar em contato com o suporte para obter assistência.
</Tip>
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para obter assistência com a atualização da sua crew ou solução de problemas de implantação.
</Card>

121
docs/pt-BR/enterprise/guides/webhook-automation.mdx Normal file
View File

@@ -0,0 +1,121 @@
---
title: "Automação com Webhook"
description: "Automatize fluxos de trabalho do CrewAI Enterprise usando webhooks com plataformas como ActivePieces, Zapier e Make.com"
icon: "webhook"
---
O CrewAI Enterprise permite que você automatize seu fluxo de trabalho usando webhooks. Este artigo irá guiá-lo no processo de configuração e uso de webhooks para iniciar a execução do crew, com foco na integração com o ActivePieces, uma plataforma de automação de fluxos de trabalho semelhante ao Zapier e Make.com.
## Configurando Webhooks
<Steps>
<Step title="Acessando a Interface de Kickoff">
- Navegue até o painel do CrewAI Enterprise
- Procure pela seção `/kickoff`, que é usada para iniciar a execução do crew
<Frame>
<img src="/images/enterprise/kickoff-interface.png" alt="Interface Kickoff" />
</Frame>
</Step>
<Step title="Configurando o Conteúdo JSON">
Na seção de Conteúdo JSON, você deverá fornecer as seguintes informações:
- **inputs**: Um objeto JSON contendo:
- `company`: O nome da empresa (ex.: "tesla")
- `product_name`: O nome do produto (ex.: "crewai")
- `form_response`: O tipo de resposta (ex.: "financial")
- `icp_description`: Uma breve descrição do Perfil de Cliente Ideal
- `product_description`: Uma breve descrição do produto
- `taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`: URLs para diversos endpoints de webhook (ActivePieces, Zapier, Make.com ou outra plataforma compatível)
</Step>
<Step title="Integração com ActivePieces">
Neste exemplo usaremos o ActivePieces. Você pode utilizar outras plataformas, como Zapier e Make.com.
Para integrar com o ActivePieces:
1. Crie um novo flow no ActivePieces
2. Adicione um gatilho (ex.: agendamento `Every Day`)
<Frame>
<img src="/images/enterprise/activepieces-trigger.png" alt="Gatilho ActivePieces" />
</Frame>
3. Adicione uma etapa de ação HTTP
- Configure a ação como `Send HTTP request`
- Use o método `POST`
- Defina a URL para o endpoint de kickoff do CrewAI Enterprise
- Adicione os headers necessários (ex.: `Bearer Token`)
<Frame>
<img src="/images/enterprise/activepieces-headers.png" alt="Headers ActivePieces" />
</Frame>
- No corpo, inclua o conteúdo JSON conforme configurado na etapa 2
<Frame>
<img src="/images/enterprise/activepieces-body.png" alt="Body ActivePieces" />
</Frame>
- O crew será iniciado no horário pré-definido.
</Step>
<Step title="Configurando o Webhook">
1. Crie um novo flow no ActivePieces e nomeie-o
<Frame>
<img src="/images/enterprise/activepieces-flow.png" alt="Flow ActivePieces" />
</Frame>
2. Adicione uma etapa de webhook como gatilho:
- Selecione `Catch Webhook` como tipo de gatilho
- Isso irá gerar uma URL única que receberá requisições HTTP e disparará seu flow
<Frame>
<img src="/images/enterprise/activepieces-webhook.png" alt="Webhook ActivePieces" />
</Frame>
- Configure o e-mail para usar o corpo de texto do webhook do crew
<Frame>
<img src="/images/enterprise/activepieces-email.png" alt="Email ActivePieces" />
</Frame>
</Step>
</Steps>
## Exemplos de Output do Webhook
<Tabs>
<Tab title="Step Webhook">
`stepWebhookUrl` - Callback executado a cada pensamento interno do agente
```json
{
"action": "**Preliminary Research Report on the Financial Industry for crewai Enterprise Solution**\n1. Industry Overview and Trends\nThe financial industry in ....\nConclusion:\nThe financial industry presents a fertile ground for implementing AI solutions like crewai, particularly in areas such as digital customer engagement, risk management, and regulatory compliance. Further engagement with the lead is recommended to better tailor the crewai solution to their specific needs and scale.",
"task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0"
}
```
</Tab>
<Tab title="Task Webhook">
`taskWebhookUrl` - Callback executado ao final de cada task
```json
{
"description": "Using the information gathered from the lead's data, conduct preliminary research on the lead's industry, company background, and potential use cases for crewai. Focus on finding relevant data that can aid in scoring the lead and planning a strategy to pitch them crewai.The financial industry presents a fertile ground for implementing AI solutions like crewai, particularly in areas such as digital customer engagement, risk management, and regulatory compliance. Further engagement with the lead is recommended to better tailor the crewai solution to their specific needs and scale.",
"task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0"
}
```
</Tab>
<Tab title="Crew Webhook">
`crewWebhookUrl` - Callback executado ao final da execução do crew
```json
{
"task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0",
"result": {
"lead_score": "Customer service enhancement, and compliance are particularly relevant.",
"talking_points": [
"Highlight how crewai's AI solutions can transform customer service with automated, personalized experiences and 24/7 support, improving both customer satisfaction and operational efficiency.",
"Discuss crewai's potential to help the institution achieve its sustainability goals through better data analysis and decision-making, contributing to responsible investing and green initiatives.",
"Emphasize crewai's ability to enhance compliance with evolving regulations through efficient data processing and reporting, reducing the risk of non-compliance penalties.",
"Stress the adaptability of crewai to support both extensive multinational operations and smaller, targeted projects, ensuring the solution grows with the institution's needs."
]
}
}
```
</Tab>
</Tabs>

103
docs/pt-BR/enterprise/guides/zapier-trigger.mdx Normal file
View File

@@ -0,0 +1,103 @@
---
title: "Trigger Zapier"
description: "Dispare crews do CrewAI a partir de fluxos de trabalho no Zapier para automatizar fluxos multiaplicativos"
icon: "bolt"
---
Este guia irá conduzi-lo pelo processo de configuração de triggers no Zapier para o CrewAI Enterprise, permitindo automatizar fluxos de trabalho entre CrewAI Enterprise e outros aplicativos.
## Pré-requisitos
- Uma conta CrewAI Enterprise
- Uma conta Zapier
- Uma conta Slack (para este exemplo específico)
## Configuração Passo a Passo
<Steps>
<Step title="Configure o Trigger do Slack">
- No Zapier, crie um novo Zap.
<Frame>
<img src="/images/enterprise/zapier-1.png" alt="Zapier 1" />
</Frame>
</Step>
<Step title="Escolha o Slack como seu app de trigger">
<Frame>
<img src="/images/enterprise/zapier-2.png" alt="Zapier 2" />
</Frame>
- Selecione `New Pushed Message` como o Evento de Trigger.
- Conecte sua conta Slack, caso ainda não tenha feito isso.
</Step>
<Step title="Configure a ação do CrewAI Enterprise">
- Adicione uma nova etapa de ação ao seu Zap.
- Escolha CrewAI+ como o app de ação e Kickoff como Evento de Ação.
<Frame>
<img src="/images/enterprise/zapier-3.png" alt="Zapier 5" />
</Frame>
</Step>
<Step title="Conecte sua conta CrewAI Enterprise">
- Conecte sua conta CrewAI Enterprise.
- Selecione o Crew apropriado para seu fluxo de trabalho.
<Frame>
<img src="/images/enterprise/zapier-4.png" alt="Zapier 6" />
</Frame>
- Configure as entradas para o Crew usando os dados da mensagem do Slack.
</Step>
<Step title="Formate a saída do CrewAI Enterprise">
- Adicione outra etapa de ação para formatar a saída de texto do CrewAI Enterprise.
- Utilize as ferramentas de formatação do Zapier para converter a saída em Markdown para HTML.
<Frame>
<img src="/images/enterprise/zapier-5.png" alt="Zapier 8" />
</Frame>
<Frame>
<img src="/images/enterprise/zapier-6.png" alt="Zapier 9" />
</Frame>
</Step>
<Step title="Envie a saída por e-mail">
- Adicione uma etapa final de ação para enviar a saída formatada por e-mail.
- Escolha seu serviço de e-mail preferido (ex.: Gmail, Outlook).
- Configure os detalhes do e-mail, incluindo destinatário, assunto e corpo.
- Insira a saída formatada do CrewAI Enterprise no corpo do e-mail.
<Frame>
<img src="/images/enterprise/zapier-7.png" alt="Zapier 7" />
</Frame>
</Step>
<Step title="Dispare o crew a partir do Slack">
- Digite o texto no seu canal do Slack
<Frame>
<img src="/images/enterprise/zapier-7b.png" alt="Zapier 10" />
</Frame>
- Selecione o botão de três pontos e então escolha Push to Zapier
<Frame>
<img src="/images/enterprise/zapier-8.png" alt="Zapier 11" />
</Frame>
</Step>
<Step title="Selecione o crew e então pressione Push to Kick Off">
<Frame>
<img src="/images/enterprise/zapier-9.png" alt="Zapier 12" />
</Frame>
</Step>
</Steps>
## Dicas para o Sucesso
- Certifique-se de que as entradas do CrewAI Enterprise estejam corretamente mapeadas a partir da mensagem do Slack.
- Teste seu Zap cuidadosamente antes de ativá-lo para identificar possíveis problemas.
- Considere adicionar etapas de tratamento de erros para gerenciar possíveis falhas no fluxo.
Seguindo estes passos, você terá configurado com sucesso triggers no Zapier para o CrewAI Enterprise, permitindo fluxos de trabalho automatizados disparados por mensagens no Slack e resultando em notificações por e-mail com a saída do CrewAI Enterprise.

253
docs/pt-BR/enterprise/integrations/asana.mdx Normal file
View File

@@ -0,0 +1,253 @@
---
title: Integração com Asana
description: "Coordenação de tarefas e projetos em equipe com a integração Asana para CrewAI."
icon: "circle"
---
## Visão Geral
Permita que seus agentes gerenciem tarefas, projetos e a coordenação da equipe através do Asana. Crie tarefas, atualize o status de projetos, gerencie atribuições e otimize o fluxo de trabalho da sua equipe com automação baseada em IA.
## Pré-requisitos
Antes de usar a integração com o Asana, assegure-se de ter:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa
- Uma conta Asana com as permissões apropriadas
- Sua conta Asana conectada através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
## Configurando a Integração Asana
### 1. Conecte sua Conta Asana
1. Acesse [CrewAI Enterprise Integrações](https://app.crewai.com/crewai_plus/connectors)
2. Encontre **Asana** na seção Integrações de Autenticação
3. Clique em **Conectar** e complete o fluxo OAuth
4. Conceda as permissões necessárias para gerenciamento de tarefas e projetos
5. Copie seu Token Enterprise em [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account)
### 2. Instale o Pacote Necessário
```bash
uv add crewai-tools
```
## Ações Disponíveis
<AccordionGroup>
<Accordion title="ASANA_CREATE_COMMENT">
**Descrição:** Cria um comentário no Asana.
**Parâmetros:**
- `task` (string, obrigatório): ID da Tarefa - O ID da tarefa à qual o comentário será adicionado. O comentário será escrito pelo usuário atualmente autenticado.
- `text` (string, obrigatório): Texto (exemplo: "Este é um comentário.").
</Accordion>
<Accordion title="ASANA_CREATE_PROJECT">
**Descrição:** Cria um projeto no Asana.
**Parâmetros:**
- `name` (string, obrigatório): Nome (exemplo: "Itens para comprar").
- `workspace` (string, obrigatório): Área de trabalho - Use as Configurações de Fluxo do Portal Connect para permitir que usuários escolham em qual área de trabalho criar projetos. Por padrão, será usada a primeira área de trabalho do usuário se deixado em branco.
- `team` (string, opcional): Equipe - Use as Configurações de Fluxo do Portal Connect para permitir que usuários escolham com qual equipe compartilhar o projeto. Por padrão, será usada a primeira equipe do usuário se deixado em branco.
- `notes` (string, opcional): Notas (exemplo: "Esses são itens que precisamos comprar.").
</Accordion>
<Accordion title="ASANA_GET_PROJECTS">
**Descrição:** Obtém uma lista de projetos do Asana.
**Parâmetros:**
- `archived` (string, opcional): Arquivado - Escolha "true" para mostrar projetos arquivados, "false" para exibir apenas projetos ativos ou "default" para mostrar ambos.
- Opções: `default`, `true`, `false`
</Accordion>
<Accordion title="ASANA_GET_PROJECT_BY_ID">
**Descrição:** Obtém um projeto pelo ID no Asana.
**Parâmetros:**
- `projectFilterId` (string, obrigatório): ID do Projeto.
</Accordion>
<Accordion title="ASANA_CREATE_TASK">
**Descrição:** Cria uma tarefa no Asana.
**Parâmetros:**
- `name` (string, obrigatório): Nome (exemplo: "Nome da tarefa").
- `workspace` (string, opcional): Área de trabalho - Use as Configurações de Fluxo do Portal Connect para permitir que usuários escolham em qual área de trabalho criar tarefas. Por padrão, será usada a primeira área de trabalho do usuário se deixado em branco.
- `project` (string, opcional): Projeto - Use as Configurações de Fluxo do Portal Connect para permitir que usuários escolham em qual projeto criar a tarefa.
- `notes` (string, opcional): Notas.
- `dueOnDate` (string, opcional): Data de Vencimento - A data em que esta tarefa deve ser concluída. Não pode ser usada em conjunto com Due At. (exemplo: "YYYY-MM-DD").
- `dueAtDate` (string, opcional): Vence Em - A data e hora (timestamp ISO) em que esta tarefa deve ser concluída. Não pode ser usada em conjunto com Due On. (exemplo: "2019-09-15T02:06:58.147Z").
- `assignee` (string, opcional): Responsável - O ID do usuário Asana a quem esta tarefa será atribuída. Use as Configurações de Fluxo do Portal Connect para permitir que usuários selecionem um responsável.
- `gid` (string, opcional): ID Externo - Um ID da sua aplicação para associar esta tarefa. Você pode usar este ID para sincronizar atualizações com esta tarefa posteriormente.
</Accordion>
<Accordion title="ASANA_UPDATE_TASK">
**Descrição:** Atualiza uma tarefa no Asana.
**Parâmetros:**
- `taskId` (string, obrigatório): ID da Tarefa - O ID da tarefa a ser atualizada.
- `completeStatus` (string, opcional): Status de Conclusão.
- Opções: `true`, `false`
- `name` (string, opcional): Nome (exemplo: "Nome da Tarefa").
- `notes` (string, opcional): Notas.
- `dueOnDate` (string, opcional): Data de Vencimento - A data em que esta tarefa deve ser concluída. Não pode ser usada junto com Due At. (exemplo: "YYYY-MM-DD").
- `dueAtDate` (string, opcional): Vence Em - A data e hora (timestamp ISO) em que esta tarefa deve ser concluída. Não pode ser usada junto com Due On. (exemplo: "2019-09-15T02:06:58.147Z").
- `assignee` (string, opcional): Responsável - O ID do usuário Asana a quem esta tarefa será atribuída. Use as Configurações de Fluxo do Portal Connect para permitir que usuários selecionem o responsável.
- `gid` (string, opcional): ID Externo - Um ID da sua aplicação para associar a tarefa. Você pode usar este ID para sincronizar atualizações posteriormente.
</Accordion>
<Accordion title="ASANA_GET_TASKS">
**Descrição:** Obtém uma lista de tarefas no Asana.
**Parâmetros:**
- `workspace` (string, opcional): Área de trabalho - O ID da área de trabalho para filtrar tarefas. Use as Configurações de Fluxo do Portal Connect para permitir que usuários selecionem uma área de trabalho.
- `project` (string, opcional): Projeto - O ID do projeto para filtrar as tarefas. Use as Configurações de Fluxo do Portal Connect para permitir que usuários selecionem um projeto.
- `assignee` (string, opcional): Responsável - O ID do responsável para filtrar tarefas. Use as Configurações de Fluxo do Portal Connect para permitir que usuários selecionem um responsável.
- `completedSince` (string, opcional): Concluída desde - Retorna apenas tarefas que estejam incompletas ou que tenham sido concluídas desde este horário (timestamp ISO ou Unix). (exemplo: "2014-04-25T16:15:47-04:00").
</Accordion>
<Accordion title="ASANA_GET_TASKS_BY_ID">
**Descrição:** Obtém uma lista de tarefas pelo ID no Asana.
**Parâmetros:**
- `taskId` (string, obrigatório): ID da Tarefa.
</Accordion>
<Accordion title="ASANA_GET_TASK_BY_EXTERNAL_ID">
**Descrição:** Obtém uma tarefa pelo ID externo no Asana.
**Parâmetros:**
- `gid` (string, obrigatório): ID Externo - O ID que esta tarefa está associada ou sincronizada, de sua aplicação.
</Accordion>
<Accordion title="ASANA_ADD_TASK_TO_SECTION">
**Descrição:** Adiciona uma tarefa a uma seção no Asana.
**Parâmetros:**
- `sectionId` (string, obrigatório): ID da Seção - O ID da seção à qual a tarefa será adicionada.
- `taskId` (string, obrigatório): ID da Tarefa - O ID da tarefa. (exemplo: "1204619611402340").
- `beforeTaskId` (string, opcional): Antes da Tarefa - O ID de uma tarefa nesta seção antes da qual esta tarefa será inserida. Não pode ser usada junto com After Task ID. (exemplo: "1204619611402340").
- `afterTaskId` (string, opcional): Após a Tarefa - O ID de uma tarefa nesta seção após a qual esta tarefa será inserida. Não pode ser usada junto com Before Task ID. (exemplo: "1204619611402340").
</Accordion>
<Accordion title="ASANA_GET_TEAMS">
**Descrição:** Obtém uma lista de equipes no Asana.
**Parâmetros:**
- `workspace` (string, obrigatório): Área de trabalho - Retorna as equipes nesta área de trabalho visíveis para o usuário autorizado.
</Accordion>
<Accordion title="ASANA_GET_WORKSPACES">
**Descrição:** Obtém uma lista de áreas de trabalho do Asana.
**Parâmetros:** Nenhum obrigatório.
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica do Agente Asana
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Get enterprise tools (Asana tools will be included)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Create an agent with Asana capabilities
asana_agent = Agent(
role="Project Manager",
goal="Manage tasks and projects in Asana efficiently",
backstory="An AI assistant specialized in project management and task coordination.",
tools=[enterprise_tools]
)
# Task to create a new project
create_project_task = Task(
description="Create a new project called 'Q1 Marketing Campaign' in the Marketing workspace",
agent=asana_agent,
expected_output="Confirmation that the project was created successfully with project ID"
)
# Run the task
crew = Crew(
agents=[asana_agent],
tasks=[create_project_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Específicas do Asana
```python
from crewai_tools import CrewaiEnterpriseTools
# Get only specific Asana tools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["asana_create_task", "asana_update_task", "asana_get_tasks"]
)
task_manager_agent = Agent(
role="Task Manager",
goal="Create and manage tasks efficiently",
backstory="An AI assistant that focuses on task creation and management.",
tools=enterprise_tools
)
# Task to create and assign a task
task_management = Task(
description="Create a task called 'Review quarterly reports' and assign it to the appropriate team member",
agent=task_manager_agent,
expected_output="Task created and assigned successfully"
)
crew = Crew(
agents=[task_manager_agent],
tasks=[task_management]
)
crew.kickoff()
```
### Gerenciamento Avançado de Projetos
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
project_coordinator = Agent(
role="Project Coordinator",
goal="Coordinate project activities and track progress",
backstory="An experienced project coordinator who ensures projects run smoothly.",
tools=[enterprise_tools]
)
# Complex task involving multiple Asana operations
coordination_task = Task(
description="""
1. Get all active projects in the workspace
2. For each project, get the list of incomplete tasks
3. Create a summary report task in the 'Management Reports' project
4. Add comments to overdue tasks to request status updates
""",
agent=project_coordinator,
expected_output="Summary report created and status update requests sent for overdue tasks"
)
crew = Crew(
agents=[project_coordinator],
tasks=[coordination_task]
)
crew.kickoff()
```

268
docs/pt-BR/enterprise/integrations/box.mdx Normal file
View File

@@ -0,0 +1,268 @@
---
title: Integração com Box
description: "Armazenamento de arquivos e gerenciamento de documentos com a integração do Box para CrewAI."
icon: "box"
---
## Visão Geral
Permita que seus agentes gerenciem arquivos, pastas e documentos através do Box. Faça upload de arquivos, organize estruturas de pastas, pesquise conteúdos e otimize o gerenciamento de documentos da sua equipe com automação alimentada por IA.
## Pré-requisitos
Antes de utilizar a integração com o Box, assegure-se de que você possui:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa
- Uma conta Box com as permissões apropriadas
- Sua conta Box conectada através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
## Configurando a Integração com o Box
### 1. Conecte sua conta Box
1. Acesse [Integrações do CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors)
2. Encontre **Box** na seção de Integrações de Autenticação
3. Clique em **Conectar** e conclua o fluxo de OAuth
4. Conceda as permissões necessárias para gerenciamento de arquivos e pastas
5. Copie seu Token Enterprise em [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account)
### 2. Instale o pacote necessário
```bash
uv add crewai-tools
```
## Ações Disponíveis
<AccordionGroup>
<Accordion title="BOX_SAVE_FILE">
**Descrição:** Salva um arquivo a partir de uma URL no Box.
**Parâmetros:**
- `fileAttributes` (object, obrigatório): Atributos - Metadados do arquivo incluindo nome, pasta pai e datas.
```json
{
"content_created_at": "2012-12-12T10:53:43-08:00",
"content_modified_at": "2012-12-12T10:53:43-08:00",
"name": "qwerty.png",
"parent": { "id": "1234567" }
}
```
- `file` (string, obrigatório): URL do arquivo - Os arquivos devem ter menos de 50MB. (exemplo: "https://picsum.photos/200/300").
</Accordion>
<Accordion title="BOX_SAVE_FILE_FROM_OBJECT">
**Descrição:** Salva um arquivo no Box.
**Parâmetros:**
- `file` (string, obrigatório): Arquivo - Aceita um Objeto de Arquivo contendo os dados. O arquivo deve ter menos de 50MB.
- `fileName` (string, obrigatório): Nome do Arquivo (exemplo: "qwerty.png").
- `folder` (string, opcional): Pasta - Use as configurações de workflow do Connect Portal para permitir que usuários escolham o destino da pasta. Caso em branco, o padrão é a pasta raiz do usuário.
</Accordion>
<Accordion title="BOX_GET_FILE_BY_ID">
**Descrição:** Obtém um arquivo pelo ID no Box.
**Parâmetros:**
- `fileId` (string, obrigatório): ID do arquivo - Identificador único que representa um arquivo. (exemplo: "12345").
</Accordion>
<Accordion title="BOX_LIST_FILES">
**Descrição:** Lista arquivos no Box.
**Parâmetros:**
- `folderId` (string, obrigatório): ID da pasta - Identificador único que representa uma pasta. (exemplo: "0").
- `filterFormula` (object, opcional): Um filtro em forma normal disjuntiva - OU de grupos E de condições únicas.
```json
{
"operator": "OR",
"conditions": [
{
"operator": "AND",
"conditions": [
{
"field": "direction",
"operator": "$stringExactlyMatches",
"value": "ASC"
}
]
}
]
}
```
</Accordion>
<Accordion title="BOX_CREATE_FOLDER">
**Descrição:** Cria uma pasta no Box.
**Parâmetros:**
- `folderName` (string, obrigatório): Nome - Nome para a nova pasta. (exemplo: "Nova Pasta").
- `folderParent` (object, obrigatório): Pasta Pai - A pasta onde a nova pasta será criada.
```json
{
"id": "123456"
}
```
</Accordion>
<Accordion title="BOX_MOVE_FOLDER">
**Descrição:** Move uma pasta no Box.
**Parâmetros:**
- `folderId` (string, obrigatório): ID da pasta - Identificador único que representa uma pasta. (exemplo: "0").
- `folderName` (string, obrigatório): Nome - Nome da pasta. (exemplo: "Nova Pasta").
- `folderParent` (object, obrigatório): Nova pasta pai de destino.
```json
{
"id": "123456"
}
```
</Accordion>
<Accordion title="BOX_GET_FOLDER_BY_ID">
**Descrição:** Obtém uma pasta pelo ID no Box.
**Parâmetros:**
- `folderId` (string, obrigatório): ID da pasta - Identificador único que representa uma pasta. (exemplo: "0").
</Accordion>
<Accordion title="BOX_SEARCH_FOLDERS">
**Descrição:** Pesquisa pastas no Box.
**Parâmetros:**
- `folderId` (string, obrigatório): ID da pasta - A pasta na qual pesquisar.
- `filterFormula` (object, opcional): Um filtro em forma normal disjuntiva - OU de grupos E de condições únicas.
```json
{
"operator": "OR",
"conditions": [
{
"operator": "AND",
"conditions": [
{
"field": "sort",
"operator": "$stringExactlyMatches",
"value": "name"
}
]
}
]
}
```
</Accordion>
<Accordion title="BOX_DELETE_FOLDER">
**Descrição:** Exclui uma pasta no Box.
**Parâmetros:**
- `folderId` (string, obrigatório): ID da pasta - Identificador único que representa uma pasta. (exemplo: "0").
- `recursive` (boolean, opcional): Recursivo - Exclui uma pasta que não está vazia, deletando de forma recursiva a pasta e todo o seu conteúdo.
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica de Agente Box
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Get enterprise tools (Box tools will be included)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Create an agent with Box capabilities
box_agent = Agent(
role="Document Manager",
goal="Manage files and folders in Box efficiently",
backstory="An AI assistant specialized in document management and file organization.",
tools=[enterprise_tools]
)
# Task to create a folder structure
create_structure_task = Task(
description="Create a folder called 'Project Files' in the root directory and upload a document from URL",
agent=box_agent,
expected_output="Folder created and file uploaded successfully"
)
# Run the task
crew = Crew(
agents=[box_agent],
tasks=[create_structure_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Específicas do Box
```python
from crewai_tools import CrewaiEnterpriseTools
# Get only specific Box tools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["box_create_folder", "box_save_file", "box_list_files"]
)
file_organizer_agent = Agent(
role="File Organizer",
goal="Organize and manage file storage efficiently",
backstory="An AI assistant that focuses on file organization and storage management.",
tools=enterprise_tools
)
# Task to organize files
organization_task = Task(
description="Create a folder structure for the marketing team and organize existing files",
agent=file_organizer_agent,
expected_output="Folder structure created and files organized"
)
crew = Crew(
agents=[file_organizer_agent],
tasks=[organization_task]
)
crew.kickoff()
```
### Gerenciamento Avançado de Arquivos
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
file_manager = Agent(
role="File Manager",
goal="Maintain organized file structure and manage document lifecycle",
backstory="An experienced file manager who ensures documents are properly organized and accessible.",
tools=[enterprise_tools]
)
# Complex task involving multiple Box operations
management_task = Task(
description="""
1. List all files in the root folder
2. Create monthly archive folders for the current year
3. Move old files to appropriate archive folders
4. Generate a summary report of the file organization
""",
agent=file_manager,
expected_output="Files organized into archive structure with summary report"
)
crew = Crew(
agents=[file_manager],
tasks=[management_task]
)
crew.kickoff()
```

293
docs/pt-BR/enterprise/integrations/clickup.mdx Normal file
View File

@@ -0,0 +1,293 @@
---
title: Integração com ClickUp
description: "Gerenciamento de tarefas e produtividade com integração ClickUp para CrewAI."
icon: "list-check"
---
## Visão Geral
Permita que seus agentes gerenciem tarefas, projetos e fluxos de produtividade por meio do ClickUp. Crie e atualize tarefas, organize projetos, gerencie a designação de equipes e otimize o gerenciamento da sua produtividade com automação impulsionada por IA.
## Pré-requisitos
Antes de utilizar a integração com o ClickUp, certifique-se de que você possui:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa
- Uma conta ClickUp com as permissões apropriadas
- Sua conta ClickUp conectada pela [Página de Integrações](https://app.crewai.com/crewai_plus/connectors)
## Configurando a Integração com o ClickUp
### 1. Conecte sua Conta ClickUp
1. Acesse [CrewAI Enterprise Integrações](https://app.crewai.com/crewai_plus/connectors)
2. Encontre **ClickUp** na seção Integrações de Autenticação
3. Clique em **Conectar** e complete o fluxo OAuth
4. Conceda as permissões necessárias para gerenciamento de tarefas e projetos
5. Copie seu Token Enterprise das [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account)
### 2. Instale o Pacote Necessário
```bash
uv add crewai-tools
```
## Ações Disponíveis
<AccordionGroup>
<Accordion title="CLICKUP_SEARCH_TASKS">
**Descrição:** Busque tarefas no ClickUp utilizando filtros avançados.
**Parâmetros:**
- `taskFilterFormula` (objeto, opcional): Um filtro em forma normal disjuntiva - OU de grupos E de condições individuais.
```json
{
"operator": "OR",
"conditions": [
{
"operator": "AND",
"conditions": [
{
"field": "statuses%5B%5D",
"operator": "$stringExactlyMatches",
"value": "open"
}
]
}
]
}
```
Campos disponíveis: `space_ids%5B%5D`, `project_ids%5B%5D`, `list_ids%5B%5D`, `statuses%5B%5D`, `include_closed`, `assignees%5B%5D`, `tags%5B%5D`, `due_date_gt`, `due_date_lt`, `date_created_gt`, `date_created_lt`, `date_updated_gt`, `date_updated_lt`
</Accordion>
<Accordion title="CLICKUP_GET_TASK_IN_LIST">
**Descrição:** Obtenha tarefas em uma lista específica do ClickUp.
**Parâmetros:**
- `listId` (string, obrigatório): Lista - Selecione uma Lista da qual obter as tarefas. Use as Configurações do Usuário no Portal de Conexão para permitir que os usuários selecionem uma Lista ClickUp.
- `taskFilterFormula` (string, opcional): Busque tarefas que correspondam aos filtros especificados. Por exemplo: name=task1.
</Accordion>
<Accordion title="CLICKUP_CREATE_TASK">
**Descrição:** Crie uma tarefa no ClickUp.
**Parâmetros:**
- `listId` (string, obrigatório): Lista - Selecione uma Lista para criar esta tarefa. Use as Configurações do Usuário no Portal de Conexão para permitir que os usuários selecionem uma Lista ClickUp.
- `name` (string, obrigatório): Nome - O nome da tarefa.
- `description` (string, opcional): Descrição - Descrição da tarefa.
- `status` (string, opcional): Status - Selecione um Status para esta tarefa. Use as Configurações do Usuário no Portal de Conexão para permitir que os usuários selecionem um Status ClickUp.
- `assignees` (string, opcional): Responsáveis - Selecione um Membro (ou um array de IDs de membros) para ser responsável por esta tarefa. Use as Configurações do Usuário no Portal de Conexão para permitir que os usuários selecionem um Membro ClickUp.
- `dueDate` (string, opcional): Data de Vencimento - Especifique uma data para a conclusão desta tarefa.
- `additionalFields` (string, opcional): Campos Adicionais - Especifique campos adicionais para incluir nesta tarefa em formato JSON.
</Accordion>
<Accordion title="CLICKUP_UPDATE_TASK">
**Descrição:** Atualize uma tarefa no ClickUp.
**Parâmetros:**
- `taskId` (string, obrigatório): ID da tarefa - O ID da tarefa a ser atualizada.
- `listId` (string, obrigatório): Lista - Selecione uma Lista para criar esta tarefa. Use as Configurações do Usuário no Portal de Conexão para permitir que os usuários selecionem uma Lista ClickUp.
- `name` (string, opcional): Nome - O nome da tarefa.
- `description` (string, opcional): Descrição - Descrição da tarefa.
- `status` (string, opcional): Status - Selecione um Status para esta tarefa. Use as Configurações do Usuário no Portal de Conexão para permitir que os usuários selecionem um Status ClickUp.
- `assignees` (string, opcional): Responsáveis - Selecione um Membro (ou um array de IDs de membros) para ser responsável por esta tarefa. Use as Configurações do Usuário no Portal de Conexão para permitir que os usuários selecionem um Membro ClickUp.
- `dueDate` (string, opcional): Data de Vencimento - Especifique uma data para a conclusão desta tarefa.
- `additionalFields` (string, opcional): Campos Adicionais - Especifique campos adicionais para incluir nesta tarefa em formato JSON.
</Accordion>
<Accordion title="CLICKUP_DELETE_TASK">
**Descrição:** Exclua uma tarefa no ClickUp.
**Parâmetros:**
- `taskId` (string, obrigatório): ID da tarefa - O ID da tarefa a ser excluída.
</Accordion>
<Accordion title="CLICKUP_GET_LIST">
**Descrição:** Obtenha informações da Lista no ClickUp.
**Parâmetros:**
- `spaceId` (string, obrigatório): ID do Espaço - O ID do espaço que contém as listas.
</Accordion>
<Accordion title="CLICKUP_GET_CUSTOM_FIELDS_IN_LIST">
**Descrição:** Obtenha Campos Personalizados em uma Lista no ClickUp.
**Parâmetros:**
- `listId` (string, obrigatório): ID da Lista - O ID da lista da qual obter os campos personalizados.
</Accordion>
<Accordion title="CLICKUP_GET_ALL_FIELDS_IN_LIST">
**Descrição:** Obtenha Todos os Campos em uma Lista no ClickUp.
**Parâmetros:**
- `listId` (string, obrigatório): ID da Lista - O ID da lista da qual obter todos os campos.
</Accordion>
<Accordion title="CLICKUP_GET_SPACE">
**Descrição:** Obtenha informações do Espaço no ClickUp.
**Parâmetros:**
- `spaceId` (string, opcional): ID do Espaço - O ID do espaço a ser recuperado.
</Accordion>
<Accordion title="CLICKUP_GET_FOLDERS">
**Descrição:** Obtenha Pastas no ClickUp.
**Parâmetros:**
- `spaceId` (string, obrigatório): ID do Espaço - O ID do espaço que contém as pastas.
</Accordion>
<Accordion title="CLICKUP_GET_MEMBER">
**Descrição:** Obtenha informações de Membro no ClickUp.
**Parâmetros:** Nenhum obrigatório.
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica do Agente ClickUp
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Get enterprise tools (ClickUp tools will be included)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Create an agent with ClickUp capabilities
clickup_agent = Agent(
role="Task Manager",
goal="Manage tasks and projects in ClickUp efficiently",
backstory="An AI assistant specialized in task management and productivity coordination.",
tools=[enterprise_tools]
)
# Task to create a new task
create_task = Task(
description="Create a task called 'Review Q1 Reports' in the Marketing list with high priority",
agent=clickup_agent,
expected_output="Task created successfully with task ID"
)
# Run the task
crew = Crew(
agents=[clickup_agent],
tasks=[create_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Específicas do ClickUp
```python
from crewai_tools import CrewaiEnterpriseTools
# Get only specific ClickUp tools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["clickup_create_task", "clickup_update_task", "clickup_search_tasks"]
)
task_coordinator = Agent(
role="Task Coordinator",
goal="Create and manage tasks efficiently",
backstory="An AI assistant that focuses on task creation and status management.",
tools=enterprise_tools
)
# Task to manage task workflow
task_workflow = Task(
description="Create a task for project planning and assign it to the development team",
agent=task_coordinator,
expected_output="Task created and assigned successfully"
)
crew = Crew(
agents=[task_coordinator],
tasks=[task_workflow]
)
crew.kickoff()
```
### Gerenciamento Avançado de Projetos
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
project_manager = Agent(
role="Project Manager",
goal="Coordinate project activities and track team productivity",
backstory="An experienced project manager who ensures projects are delivered on time.",
tools=[enterprise_tools]
)
# Complex task involving multiple ClickUp operations
project_coordination = Task(
description="""
1. Get all open tasks in the current space
2. Identify overdue tasks and update their status
3. Create a weekly report task summarizing project progress
4. Assign the report task to the team lead
""",
agent=project_manager,
expected_output="Project status updated and weekly report task created and assigned"
)
crew = Crew(
agents=[project_manager],
tasks=[project_coordination]
)
crew.kickoff()
```
### Busca e Gerenciamento de Tarefas
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
task_analyst = Agent(
role="Task Analyst",
goal="Analyze task patterns and optimize team productivity",
backstory="An AI assistant that analyzes task data to improve team efficiency.",
tools=[enterprise_tools]
)
# Task to analyze and optimize task distribution
task_analysis = Task(
description="""
Search for all tasks assigned to team members in the last 30 days,
analyze completion patterns, and create optimization recommendations
""",
agent=task_analyst,
expected_output="Task analysis report with optimization recommendations"
)
crew = Crew(
agents=[task_analyst],
tasks=[task_analysis]
)
crew.kickoff()
```
### Precisa de Ajuda?
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para auxílio na configuração ou solução de problemas da integração com ClickUp.
</Card>

323
docs/pt-BR/enterprise/integrations/github.mdx Normal file
View File

@@ -0,0 +1,323 @@
---
title: Integração com GitHub
description: "Gerenciamento de repositórios e issues com a integração do GitHub para CrewAI."
icon: "github"
---
## Visão Geral
Permita que seus agentes gerenciem repositórios, issues e releases através do GitHub. Crie e atualize issues, gerencie releases, acompanhe o desenvolvimento do projeto e otimize seu fluxo de trabalho de desenvolvimento de software com automação alimentada por IA.
## Pré-requisitos
Antes de usar a integração do GitHub, assegure-se de ter:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa
- Uma conta GitHub com permissões adequadas no repositório
- Conta do GitHub conectada através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
## Configurando a Integração com GitHub
### 1. Conecte sua conta GitHub
1. Acesse [Integrações CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors)
2. Encontre **GitHub** na seção de Integrações de Autenticação
3. Clique em **Conectar** e complete o fluxo OAuth
4. Conceda as permissões necessárias para gerenciamento de repositório e issues
5. Copie seu Token Enterprise nas [Configurações de Conta](https://app.crewai.com/crewai_plus/settings/account)
### 2. Instale o pacote necessário
```bash
uv add crewai-tools
```
## Ações Disponíveis
<AccordionGroup>
<Accordion title="GITHUB_CREATE_ISSUE">
**Descrição:** Cria uma issue no GitHub.
**Parâmetros:**
- `owner` (string, obrigatório): Proprietário - Especifique o nome do proprietário da conta do repositório associado a esta Issue. (exemplo: "abc").
- `repo` (string, obrigatório): Repositório - Especifique o nome do repositório associado a esta Issue.
- `title` (string, obrigatório): Título da Issue - Especifique o título da issue a ser criada.
- `body` (string, opcional): Corpo da Issue - Especifique o conteúdo do corpo da issue a ser criada.
- `assignees` (string, opcional): Responsáveis - Especifique o login dos responsáveis no GitHub como um array de strings para esta issue. (exemplo: `["octocat"]`).
</Accordion>
<Accordion title="GITHUB_UPDATE_ISSUE">
**Descrição:** Atualiza uma issue no GitHub.
**Parâmetros:**
- `owner` (string, obrigatório): Proprietário - Especifique o nome do proprietário da conta do repositório associado a esta Issue. (exemplo: "abc").
- `repo` (string, obrigatório): Repositório - Especifique o nome do repositório associado a esta Issue.
- `issue_number` (string, obrigatório): Número da Issue - Especifique o número da issue a ser atualizada.
- `title` (string, obrigatório): Título da Issue - Especifique o título da issue a ser atualizada.
- `body` (string, opcional): Corpo da Issue - Especifique o conteúdo do corpo da issue a ser atualizada.
- `assignees` (string, opcional): Responsáveis - Especifique o login dos responsáveis no GitHub como um array de strings para esta issue. (exemplo: `["octocat"]`).
- `state` (string, opcional): Estado - Especifique o estado atualizado da issue.
- Opções: `open`, `closed`
</Accordion>
<Accordion title="GITHUB_GET_ISSUE_BY_NUMBER">
**Descrição:** Obtém uma issue pelo número no GitHub.
**Parâmetros:**
- `owner` (string, obrigatório): Proprietário - Especifique o nome do proprietário da conta do repositório associado a esta Issue. (exemplo: "abc").
- `repo` (string, obrigatório): Repositório - Especifique o nome do repositório associado a esta Issue.
- `issue_number` (string, obrigatório): Número da Issue - Especifique o número da issue a ser buscada.
</Accordion>
<Accordion title="GITHUB_LOCK_ISSUE">
**Descrição:** Bloqueia uma issue no GitHub.
**Parâmetros:**
- `owner` (string, obrigatório): Proprietário - Especifique o nome do proprietário da conta do repositório associado a esta Issue. (exemplo: "abc").
- `repo` (string, obrigatório): Repositório - Especifique o nome do repositório associado a esta Issue.
- `issue_number` (string, obrigatório): Número da Issue - Especifique o número da issue a ser bloqueada.
- `lock_reason` (string, obrigatório): Motivo do Bloqueio - Especifique um motivo para bloquear a discussão da issue ou pull request.
- Opções: `off-topic`, `too heated`, `resolved`, `spam`
</Accordion>
<Accordion title="GITHUB_SEARCH_ISSUE">
**Descrição:** Busca por issues no GitHub.
**Parâmetros:**
- `owner` (string, obrigatório): Proprietário - Especifique o nome do proprietário da conta do repositório associado a esta Issue. (exemplo: "abc").
- `repo` (string, obrigatório): Repositório - Especifique o nome do repositório associado a esta Issue.
- `filter` (object, obrigatório): Um filtro em forma normal disjuntiva - OU de grupos E de condições simples.
```json
{
"operator": "OR",
"conditions": [
{
"operator": "AND",
"conditions": [
{
"field": "assignee",
"operator": "$stringExactlyMatches",
"value": "octocat"
}
]
}
]
}
```
Campos disponíveis: `assignee`, `creator`, `mentioned`, `labels`
</Accordion>
<Accordion title="GITHUB_CREATE_RELEASE">
**Descrição:** Cria um release no GitHub.
**Parâmetros:**
- `owner` (string, obrigatório): Proprietário - Especifique o nome do proprietário da conta do repositório associado a este Release. (exemplo: "abc").
- `repo` (string, obrigatório): Repositório - Especifique o nome do repositório associado a este Release.
- `tag_name` (string, obrigatório): Nome - Especifique o nome da tag do release a ser criada. (exemplo: "v1.0.0").
- `target_commitish` (string, opcional): Destino - Especifique o destino do release. Pode ser o nome de um branch ou o SHA de um commit. Padrão é o branch principal. (exemplo: "master").
- `body` (string, opcional): Descrição - Especifique uma descrição para este release.
- `draft` (string, opcional): Rascunho - Especifique se o release criado deve ser um rascunho (não publicado).
- Opções: `true`, `false`
- `prerelease` (string, opcional): Pré-lançamento - Especifique se o release criado deve ser um pré-lançamento.
- Opções: `true`, `false`
- `discussion_category_name` (string, opcional): Nome da Categoria de Discussão - Se especificado, uma discussão da categoria indicada é criada e vinculada ao release. O valor deve ser uma categoria já existente no repositório.
- `generate_release_notes` (string, opcional): Notas de Release - Especifique se o release criado deve criar automaticamente notas de release usando o nome e a descrição fornecidos.
- Opções: `true`, `false`
</Accordion>
<Accordion title="GITHUB_UPDATE_RELEASE">
**Descrição:** Atualiza um release no GitHub.
**Parâmetros:**
- `owner` (string, obrigatório): Proprietário - Especifique o nome do proprietário da conta do repositório associado a este Release. (exemplo: "abc").
- `repo` (string, obrigatório): Repositório - Especifique o nome do repositório associado a este Release.
- `id` (string, obrigatório): ID do Release - Especifique o ID do release a ser atualizado.
- `tag_name` (string, opcional): Nome - Especifique o nome da tag do release a ser atualizado. (exemplo: "v1.0.0").
- `target_commitish` (string, opcional): Destino - Especifique o destino do release. Pode ser o nome de um branch ou o SHA de um commit. Padrão é o branch principal. (exemplo: "master").
- `body` (string, opcional): Descrição - Especifique uma descrição para este release.
- `draft` (string, opcional): Rascunho - Especifique se o release criado deve ser um rascunho (não publicado).
- Opções: `true`, `false`
- `prerelease` (string, opcional): Pré-lançamento - Especifique se o release criado deve ser um pré-lançamento.
- Opções: `true`, `false`
- `discussion_category_name` (string, opcional): Nome da Categoria de Discussão - Se especificado, uma discussão da categoria indicada é criada e vinculada ao release. O valor deve ser uma categoria já existente no repositório.
- `generate_release_notes` (string, opcional): Notas de Release - Especifique se o release criado deve criar automaticamente notas de release usando o nome e a descrição fornecidos.
- Opções: `true`, `false`
</Accordion>
<Accordion title="GITHUB_GET_RELEASE_BY_ID">
**Descrição:** Obtém um release por ID no GitHub.
**Parâmetros:**
- `owner` (string, obrigatório): Proprietário - Especifique o nome do proprietário da conta do repositório associado a este Release. (exemplo: "abc").
- `repo` (string, obrigatório): Repositório - Especifique o nome do repositório associado a este Release.
- `id` (string, obrigatório): ID do Release - Especifique o ID do release a ser recuperado.
</Accordion>
<Accordion title="GITHUB_GET_RELEASE_BY_TAG_NAME">
**Descrição:** Obtém um release pelo nome da tag no GitHub.
**Parâmetros:**
- `owner` (string, obrigatório): Proprietário - Especifique o nome do proprietário da conta do repositório associado a este Release. (exemplo: "abc").
- `repo` (string, obrigatório): Repositório - Especifique o nome do repositório associado a este Release.
- `tag_name` (string, obrigatório): Nome - Especifique o nome da tag do release a ser recuperado. (exemplo: "v1.0.0").
</Accordion>
<Accordion title="GITHUB_DELETE_RELEASE">
**Descrição:** Exclui um release no GitHub.
**Parâmetros:**
- `owner` (string, obrigatório): Proprietário - Especifique o nome do proprietário da conta do repositório associado a este Release. (exemplo: "abc").
- `repo` (string, obrigatório): Repositório - Especifique o nome do repositório associado a este Release.
- `id` (string, obrigatório): ID do Release - Especifique o ID do release a ser excluído.
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica de Agente GitHub
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Get enterprise tools (GitHub tools will be included)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Create an agent with GitHub capabilities
github_agent = Agent(
role="Repository Manager",
goal="Manage GitHub repositories, issues, and releases efficiently",
backstory="An AI assistant specialized in repository management and issue tracking.",
tools=[enterprise_tools]
)
# Task to create a new issue
create_issue_task = Task(
description="Create a bug report issue for the login functionality in the main repository",
agent=github_agent,
expected_output="Issue created successfully with issue number"
)
# Run the task
crew = Crew(
agents=[github_agent],
tasks=[create_issue_task]
)
crew.kickoff()
```
### Filtrando Ferramentas GitHub Específicas
```python
from crewai_tools import CrewaiEnterpriseTools
# Get only specific GitHub tools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["github_create_issue", "github_update_issue", "github_search_issue"]
)
issue_manager = Agent(
role="Issue Manager",
goal="Create and manage GitHub issues efficiently",
backstory="An AI assistant that focuses on issue tracking and management.",
tools=enterprise_tools
)
# Task to manage issue workflow
issue_workflow = Task(
description="Create a feature request issue and assign it to the development team",
agent=issue_manager,
expected_output="Feature request issue created and assigned successfully"
)
crew = Crew(
agents=[issue_manager],
tasks=[issue_workflow]
)
crew.kickoff()
```
### Gerenciamento de Releases
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
release_manager = Agent(
role="Release Manager",
goal="Manage software releases and versioning",
backstory="An experienced release manager who handles version control and release processes.",
tools=[enterprise_tools]
)
# Task to create a new release
release_task = Task(
description="""
Create a new release v2.1.0 for the project with:
- Auto-generated release notes
- Target the main branch
- Include a description of new features and bug fixes
""",
agent=release_manager,
expected_output="Release v2.1.0 created successfully with release notes"
)
crew = Crew(
agents=[release_manager],
tasks=[release_task]
)
crew.kickoff()
```
### Acompanhamento e Gerenciamento de Issues
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
project_coordinator = Agent(
role="Project Coordinator",
goal="Track and coordinate project issues and development progress",
backstory="An AI assistant that helps coordinate development work and track project progress.",
tools=[enterprise_tools]
)
# Complex task involving multiple GitHub operations
coordination_task = Task(
description="""
1. Search for all open issues assigned to the current milestone
2. Identify overdue issues and update their priority labels
3. Create a weekly progress report issue
4. Lock resolved issues that have been inactive for 30 days
""",
agent=project_coordinator,
expected_output="Project coordination completed with progress report and issue management"
)
crew = Crew(
agents=[project_coordinator],
tasks=[coordination_task]
)
crew.kickoff()
```
### Obtendo Ajuda
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para auxílio na configuração ou solução de problemas com a integração do GitHub.
</Card>

356
docs/pt-BR/enterprise/integrations/gmail.mdx Normal file
View File

@@ -0,0 +1,356 @@
---
title: Integração com Gmail
description: "Gerenciamento de e-mails e contatos com a integração do Gmail para o CrewAI."
icon: "envelope"
---
## Visão Geral
Permita que seus agentes gerenciem e-mails, contatos e rascunhos através do Gmail. Envie e-mails, pesquise mensagens, gerencie contatos, crie rascunhos e otimize suas comunicações por e-mail com automação impulsionada por IA.
## Pré-requisitos
Antes de usar a integração com o Gmail, certifique-se de que você possui:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa
- Uma conta do Gmail com as permissões adequadas
- Conectou sua conta do Gmail através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
## Configurando a Integração com o Gmail
### 1. Conecte sua Conta do Gmail
1. Navegue até [Integrações CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors)
2. Encontre **Gmail** na seção de Integrações de Autenticação
3. Clique em **Conectar** e conclua o fluxo OAuth
4. Conceda as permissões necessárias para o gerenciamento de e-mail e contato
5. Copie seu Token Empresarial em [Configurações de Conta](https://app.crewai.com/crewai_plus/settings/account)
### 2. Instale o Pacote Necessário
```bash
uv add crewai-tools
```
## Ações Disponíveis
<AccordionGroup>
<Accordion title="GMAIL_SEND_EMAIL">
**Descrição:** Envia um e-mail pelo Gmail.
**Parâmetros:**
- `toRecipients` (array, obrigatório): Para - Especifique os destinatários como uma única string ou um array JSON.
```json
[
"recipient1@domain.com",
"recipient2@domain.com"
]
```
- `from` (string, obrigatório): De - Especifique o e-mail do remetente.
- `subject` (string, obrigatório): Assunto - Especifique o assunto da mensagem.
- `messageContent` (string, obrigatório): Conteúdo da Mensagem - Especifique o conteúdo do e-mail em texto simples ou HTML.
- `attachments` (string, opcional): Anexos - Aceita um único objeto de arquivo ou um array JSON de objetos de arquivo.
- `additionalHeaders` (object, opcional): Cabeçalhos Adicionais - Especifique quaisquer campos de cabeçalho adicionais aqui.
```json
{
"reply-to": "Nome do Remetente <sender@domain.com>"
}
```
</Accordion>
<Accordion title="GMAIL_GET_EMAIL_BY_ID">
**Descrição:** Obtém um e-mail pelo ID no Gmail.
**Parâmetros:**
- `userId` (string, obrigatório): ID do Usuário - Especifique o endereço de e-mail do usuário. (exemplo: "user@domain.com").
- `messageId` (string, obrigatório): ID da Mensagem - Especifique o ID da mensagem a ser recuperada.
</Accordion>
<Accordion title="GMAIL_SEARCH_FOR_EMAIL">
**Descrição:** Pesquisa e-mails no Gmail usando filtros avançados.
**Parâmetros:**
- `emailFilterFormula` (object, opcional): Um filtro na forma normal disjuntiva - OU de grupos E de condições únicas.
```json
{
"operator": "OR",
"conditions": [
{
"operator": "AND",
"conditions": [
{
"field": "from",
"operator": "$stringContains",
"value": "example@domain.com"
}
]
}
]
}
```
Campos disponíveis: `from`, `to`, `date`, `label`, `subject`, `cc`, `bcc`, `category`, `deliveredto:`, `size`, `filename`, `older_than`, `newer_than`, `list`, `is:important`, `is:unread`, `is:snoozed`, `is:starred`, `is:read`, `has:drive`, `has:document`, `has:spreadsheet`, `has:presentation`, `has:attachment`, `has:youtube`, `has:userlabels`
- `paginationParameters` (object, opcional): Parâmetros de Paginação.
```json
{
"pageCursor": "page_cursor_string"
}
```
</Accordion>
<Accordion title="GMAIL_DELETE_EMAIL">
**Descrição:** Exclui um e-mail no Gmail.
**Parâmetros:**
- `userId` (string, obrigatório): ID do Usuário - Especifique o endereço de e-mail do usuário. (exemplo: "user@domain.com").
- `messageId` (string, obrigatório): ID da Mensagem - Especifique o ID da mensagem para enviar para a lixeira.
</Accordion>
<Accordion title="GMAIL_CREATE_A_CONTACT">
**Descrição:** Cria um contato no Gmail.
**Parâmetros:**
- `givenName` (string, obrigatório): Primeiro Nome - Especifique o Primeiro Nome do contato a ser criado. (exemplo: "João").
- `familyName` (string, obrigatório): Sobrenome - Especifique o Sobrenome do contato a ser criado. (exemplo: "Silva").
- `email` (string, obrigatório): E-mail - Especifique o endereço de e-mail do contato a ser criado.
- `additionalFields` (object, opcional): Campos Adicionais - Informações adicionais de contato.
```json
{
"addresses": [
{
"streetAddress": "1000 North St.",
"city": "Los Angeles"
}
]
}
```
</Accordion>
<Accordion title="GMAIL_GET_CONTACT_BY_RESOURCE_NAME">
**Descrição:** Obtém um contato pelo nome do recurso no Gmail.
**Parâmetros:**
- `resourceName` (string, obrigatório): Nome do Recurso - Especifique o nome do recurso do contato a ser buscado.
</Accordion>
<Accordion title="GMAIL_SEARCH_FOR_CONTACT">
**Descrição:** Pesquisa um contato no Gmail.
**Parâmetros:**
- `searchTerm` (string, obrigatório): Termo - Especifique um termo para buscar correspondências aproximadas ou exatas nos campos nome, apelido, endereços de e-mail, números de telefone ou organizações do contato.
</Accordion>
<Accordion title="GMAIL_DELETE_CONTACT">
**Descrição:** Exclui um contato no Gmail.
**Parâmetros:**
- `resourceName` (string, obrigatório): Nome do Recurso - Especifique o nome do recurso do contato a ser excluído.
</Accordion>
<Accordion title="GMAIL_CREATE_DRAFT">
**Descrição:** Cria um rascunho no Gmail.
**Parâmetros:**
- `toRecipients` (array, opcional): Para - Especifique os destinatários como uma única string ou um array JSON.
```json
[
"recipient1@domain.com",
"recipient2@domain.com"
]
```
- `from` (string, opcional): De - Especifique o e-mail do remetente.
- `subject` (string, opcional): Assunto - Especifique o assunto da mensagem.
- `messageContent` (string, opcional): Conteúdo da Mensagem - Especifique o conteúdo do e-mail em texto simples ou HTML.
- `attachments` (string, opcional): Anexos - Aceita um único objeto de arquivo ou um array JSON de objetos de arquivo.
- `additionalHeaders` (object, opcional): Cabeçalhos Adicionais - Especifique quaisquer campos de cabeçalho adicionais aqui.
```json
{
"reply-to": "Nome do Remetente <sender@domain.com>"
}
```
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica de Agente Gmail
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Get enterprise tools (Gmail tools will be included)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Create an agent with Gmail capabilities
gmail_agent = Agent(
role="Email Manager",
goal="Manage email communications and contacts efficiently",
backstory="An AI assistant specialized in email management and communication.",
tools=[enterprise_tools]
)
# Task to send a follow-up email
send_email_task = Task(
description="Send a follow-up email to john@example.com about the project update meeting",
agent=gmail_agent,
expected_output="Email sent successfully with confirmation"
)
# Run the task
crew = Crew(
agents=[gmail_agent],
tasks=[send_email_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Específicas do Gmail
```python
from crewai_tools import CrewaiEnterpriseTools
# Get only specific Gmail tools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["gmail_send_email", "gmail_search_for_email", "gmail_create_draft"]
)
email_coordinator = Agent(
role="Email Coordinator",
goal="Coordinate email communications and manage drafts",
backstory="An AI assistant that focuses on email coordination and draft management.",
tools=enterprise_tools
)
# Task to prepare and send emails
email_coordination = Task(
description="Search for emails from the marketing team, create a summary draft, and send it to stakeholders",
agent=email_coordinator,
expected_output="Summary email sent to stakeholders"
)
crew = Crew(
agents=[email_coordinator],
tasks=[email_coordination]
)
crew.kickoff()
```
### Gerenciamento de Contatos
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
contact_manager = Agent(
role="Contact Manager",
goal="Manage and organize email contacts efficiently",
backstory="An experienced contact manager who maintains organized contact databases.",
tools=[enterprise_tools]
)
# Task to manage contacts
contact_task = Task(
description="""
1. Search for contacts from the 'example.com' domain
2. Create new contacts for recent email senders not in the contact list
3. Update contact information with recent interaction data
""",
agent=contact_manager,
expected_output="Contact database updated with new contacts and recent interactions"
)
crew = Crew(
agents=[contact_manager],
tasks=[contact_task]
)
crew.kickoff()
```
### Pesquisa e Análise de E-mails
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
email_analyst = Agent(
role="Email Analyst",
goal="Analyze email patterns and provide insights",
backstory="An AI assistant that analyzes email data to provide actionable insights.",
tools=[enterprise_tools]
)
# Task to analyze email patterns
analysis_task = Task(
description="""
Search for all unread emails from the last 7 days,
categorize them by sender domain,
and create a summary report of communication patterns
""",
agent=email_analyst,
expected_output="Email analysis report with communication patterns and recommendations"
)
crew = Crew(
agents=[email_analyst],
tasks=[analysis_task]
)
crew.kickoff()
```
### Fluxos de Trabalho Automatizados de E-mail
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
workflow_manager = Agent(
role="Email Workflow Manager",
goal="Automate email workflows and responses",
backstory="An AI assistant that manages automated email workflows and responses.",
tools=[enterprise_tools]
)
# Complex task involving multiple Gmail operations
workflow_task = Task(
description="""
1. Search for emails with 'urgent' in the subject from the last 24 hours
2. Create draft responses for each urgent email
3. Send automated acknowledgment emails to senders
4. Create a summary report of urgent items requiring attention
""",
agent=workflow_manager,
expected_output="Urgent emails processed with automated responses and summary report"
)
crew = Crew(
agents=[workflow_manager],
tasks=[workflow_task]
)
crew.kickoff()
```
### Precisa de Ajuda?
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nosso time de suporte para obter assistência na configuração ou solução de problemas da integração Gmail.
</Card>

391
docs/pt-BR/enterprise/integrations/google_calendar.mdx Normal file
View File

@@ -0,0 +1,391 @@
---
title: Integração com Google Calendar
description: "Gerenciamento de eventos e agendas com integração ao Google Calendar para o CrewAI."
icon: "calendar"
---
## Visão Geral
Permita que seus agentes gerenciem eventos de calendário, agendas e disponibilidade através do Google Calendar. Crie e atualize eventos, gerencie participantes, verifique disponibilidade e otimize seu fluxo de agendamento com automação potencializada por IA.
## Pré-requisitos
Antes de usar a integração com o Google Calendar, certifique-se de ter:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa
- Uma conta Google com acesso ao Google Calendar
- Sua conta Google conectada pela [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
## Configurando a Integração com Google Calendar
### 1. Conecte sua Conta Google
1. Acesse [Integrações do CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors)
2. Encontre **Google Calendar** na seção de Integrações de Autenticação
3. Clique em **Conectar** e complete o fluxo OAuth
4. Conceda as permissões necessárias para acesso ao calendário e contatos
5. Copie seu Token Enterprise nas [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account)
### 2. Instale o Pacote Necessário
```bash
uv add crewai-tools
```
## Ações Disponíveis
<AccordionGroup>
<Accordion title="GOOGLE_CALENDAR_CREATE_EVENT">
**Descrição:** Cria um evento no Google Calendar.
**Parâmetros:**
- `eventName` (string, obrigatório): Nome do evento.
- `startTime` (string, obrigatório): Horário de início – Aceita timestamp Unix ou formatos de data ISO8601.
- `endTime` (string, opcional): Horário de término – Padrão para uma hora após o início, se deixado em branco.
- `calendar` (string, opcional): Calendário – Use as Configurações de Workflow do Connect Portal para permitir que o usuário selecione em qual calendário o evento será adicionado. Padrão para o calendário principal do usuário se deixado em branco.
- `attendees` (string, opcional): Participantes – Aceita um array de e-mails ou e-mails separados por vírgula.
- `eventLocation` (string, opcional): Local do evento.
- `eventDescription` (string, opcional): Descrição do evento.
- `eventId` (string, opcional): ID do evento – Um ID da sua aplicação para associar a este evento. Você pode usar esse ID para sincronizar atualizações posteriores neste evento.
- `includeMeetLink` (boolean, opcional): Incluir link do Google Meet? – Cria automaticamente um link para conferência Google Meet para este evento.
</Accordion>
<Accordion title="GOOGLE_CALENDAR_UPDATE_EVENT">
**Descrição:** Atualiza um evento existente no Google Calendar.
**Parâmetros:**
- `eventId` (string, obrigatório): ID do evento – O ID do evento a ser atualizado.
- `eventName` (string, opcional): Nome do evento.
- `startTime` (string, opcional): Horário de início – Aceita timestamp Unix ou formatos de data ISO8601.
- `endTime` (string, opcional): Horário de término – Padrão para uma hora após o início, se deixado em branco.
- `calendar` (string, opcional): Calendário – Use as Configurações de Workflow do Connect Portal para permitir que o usuário selecione em qual calendário o evento será adicionado. Padrão para o calendário principal do usuário se deixado em branco.
- `attendees` (string, opcional): Participantes – Aceita um array de e-mails ou e-mails separados por vírgula.
- `eventLocation` (string, opcional): Local do evento.
- `eventDescription` (string, opcional): Descrição do evento.
</Accordion>
<Accordion title="GOOGLE_CALENDAR_LIST_EVENTS">
**Descrição:** Lista eventos do Google Calendar.
**Parâmetros:**
- `calendar` (string, opcional): Calendário – Use as Configurações de Workflow do Connect Portal para permitir que o usuário selecione em qual calendário o evento será adicionado. Padrão para o calendário principal do usuário se deixado em branco.
- `after` (string, opcional): Após – Filtra eventos que começam após a data fornecida (Unix em milissegundos ou timestamp ISO). (exemplo: "2025-04-12T10:00:00Z ou 1712908800000").
- `before` (string, opcional): Antes – Filtra eventos que terminam antes da data fornecida (Unix em milissegundos ou timestamp ISO). (exemplo: "2025-04-12T10:00:00Z ou 1712908800000").
</Accordion>
<Accordion title="GOOGLE_CALENDAR_GET_EVENT_BY_ID">
**Descrição:** Obtém um evento específico pelo ID no Google Calendar.
**Parâmetros:**
- `eventId` (string, obrigatório): ID do evento.
- `calendar` (string, opcional): Calendário – Use as Configurações de Workflow do Connect Portal para permitir que o usuário selecione em qual calendário o evento será adicionado. Padrão para o calendário principal do usuário se deixado em branco.
</Accordion>
<Accordion title="GOOGLE_CALENDAR_DELETE_EVENT">
**Descrição:** Exclui um evento do Google Calendar.
**Parâmetros:**
- `eventId` (string, obrigatório): ID do evento – O ID do evento do calendário a ser excluído.
- `calendar` (string, opcional): Calendário – Use as Configurações de Workflow do Connect Portal para permitir que o usuário selecione em qual calendário o evento será adicionado. Padrão para o calendário principal do usuário se deixado em branco.
</Accordion>
<Accordion title="GOOGLE_CALENDAR_GET_CONTACTS">
**Descrição:** Obtém contatos do Google Calendar.
**Parâmetros:**
- `paginationParameters` (objeto, opcional): Parâmetros de Paginação.
```json
{
"pageCursor": "page_cursor_string"
}
```
</Accordion>
<Accordion title="GOOGLE_CALENDAR_SEARCH_CONTACTS">
**Descrição:** Pesquisa contatos no Google Calendar.
**Parâmetros:**
- `query` (string, opcional): Termo de pesquisa para buscar contatos.
</Accordion>
<Accordion title="GOOGLE_CALENDAR_LIST_DIRECTORY_PEOPLE">
**Descrição:** Lista pessoas do diretório.
**Parâmetros:**
- `paginationParameters` (objeto, opcional): Parâmetros de Paginação.
```json
{
"pageCursor": "page_cursor_string"
}
```
</Accordion>
<Accordion title="GOOGLE_CALENDAR_SEARCH_DIRECTORY_PEOPLE">
**Descrição:** Pesquisa pessoas no diretório.
**Parâmetros:**
- `query` (string, obrigatório): Termo de pesquisa para buscar contatos.
- `paginationParameters` (objeto, opcional): Parâmetros de Paginação.
```json
{
"pageCursor": "page_cursor_string"
}
```
</Accordion>
<Accordion title="GOOGLE_CALENDAR_LIST_OTHER_CONTACTS">
**Descrição:** Lista outros contatos.
**Parâmetros:**
- `paginationParameters` (objeto, opcional): Parâmetros de Paginação.
```json
{
"pageCursor": "page_cursor_string"
}
```
</Accordion>
<Accordion title="GOOGLE_CALENDAR_SEARCH_OTHER_CONTACTS">
**Descrição:** Pesquisa outros contatos.
**Parâmetros:**
- `query` (string, opcional): Termo de pesquisa para buscar contatos.
</Accordion>
<Accordion title="GOOGLE_CALENDAR_GET_AVAILABILITY">
**Descrição:** Obtém informações de disponibilidade para calendários.
**Parâmetros:**
- `timeMin` (string, obrigatório): Início do intervalo. Em formato ISO.
- `timeMax` (string, obrigatório): Fim do intervalo. Em formato ISO.
- `timeZone` (string, opcional): Fuso horário usado na resposta. Opcional. O padrão é UTC.
- `items` (array, opcional): Lista de calendários e/ou grupos para consulta. Padrão para o calendário padrão do usuário.
```json
[
{
"id": "calendar_id_1"
},
{
"id": "calendar_id_2"
}
]
```
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica de Agente de Calendário
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Obter ferramentas empresariais (as ferramentas do Google Calendar serão incluídas)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Criar um agente com capacidades do Google Calendar
calendar_agent = Agent(
role="Schedule Manager",
goal="Gerenciar eventos de calendário e agendamento de maneira eficiente",
backstory="Um assistente de IA especializado em gerenciamento de agendas e coordenação de horários.",
tools=[enterprise_tools]
)
# Tarefa de criação de reunião
create_meeting_task = Task(
description="Crie uma reunião diária de equipe amanhã às 9h com o time de desenvolvimento",
agent=calendar_agent,
expected_output="Reunião criada com sucesso com link do Google Meet"
)
# Executar a tarefa
crew = Crew(
agents=[calendar_agent],
tasks=[create_meeting_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Específicas do Calendário
```python
from crewai_tools import CrewaiEnterpriseTools
# Obter apenas ferramentas específicas do Google Calendar
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["google_calendar_create_event", "google_calendar_list_events", "google_calendar_get_availability"]
)
meeting_coordinator = Agent(
role="Meeting Coordinator",
goal="Coordenar reuniões e verificar disponibilidade",
backstory="Um assistente de IA que foca em agendamento de reuniões e gerenciamento de disponibilidade.",
tools=enterprise_tools
)
# Tarefa para agendar reunião com verificação de disponibilidade
schedule_meeting = Task(
description="Verifique a disponibilidade para a próxima semana e agende uma reunião de revisão do projeto com os stakeholders",
agent=meeting_coordinator,
expected_output="Reunião agendada após verificação da disponibilidade de todos os participantes"
)
crew = Crew(
agents=[meeting_coordinator],
tasks=[schedule_meeting]
)
crew.kickoff()
```
### Gerenciamento e Atualização de Eventos
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
event_manager = Agent(
role="Event Manager",
goal="Gerenciar e atualizar eventos de calendário de forma eficiente",
backstory="Um experiente gestor de eventos responsável pela logística e atualizações dos eventos.",
tools=[enterprise_tools]
)
# Tarefa para gerenciar atualizações de eventos
event_management = Task(
description="""
1. Liste todos os eventos desta semana
2. Atualize os eventos que precisarem de alteração de local para incluir links de videoconferência
3. Envie convites de calendário para novos membros do time para reuniões recorrentes
""",
agent=event_manager,
expected_output="Eventos semanais atualizados com os locais corretos e novos participantes incluídos"
)
crew = Crew(
agents=[event_manager],
tasks=[event_management]
)
crew.kickoff()
```
### Gerenciamento de Contatos e Disponibilidade
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
availability_coordinator = Agent(
role="Availability Coordinator",
goal="Coordenar disponibilidade e gerenciar contatos para agendamento",
backstory="Um assistente de IA que se especializa em gerenciamento de disponibilidade e coordenação de contatos.",
tools=[enterprise_tools]
)
# Tarefa de coordenação de disponibilidade
availability_task = Task(
description="""
1. Pesquise contatos no departamento de engenharia
2. Verifique a disponibilidade de todos os engenheiros para a próxima sexta-feira à tarde
3. Crie uma reunião de equipe no primeiro intervalo de 2 horas disponível
4. Inclua o link do Google Meet e envie convites
""",
agent=availability_coordinator,
expected_output="Reunião agendada com base na disponibilidade com todos os engenheiros convidados"
)
crew = Crew(
agents=[availability_coordinator],
tasks=[availability_task]
)
crew.kickoff()
```
### Workflows de Agendamento Automatizado
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
scheduling_automator = Agent(
role="Scheduling Automator",
goal="Automatizar workflows de agendamento e gerenciamento de calendários",
backstory="Um assistente de IA que automatiza cenários complexos de agendamento e workflows de agenda.",
tools=[enterprise_tools]
)
# Tarefa de automação de agendamento complexo
automation_task = Task(
description="""
1. Liste todos os eventos futuros das próximas duas semanas
2. Identifique conflitos de agendamento ou reuniões consecutivas
3. Sugira horários ótimos de reunião verificando as disponibilidades
4. Crie intervalos entre reuniões quando necessário
5. Atualize a descrição dos eventos com pautas e links de reunião
""",
agent=scheduling_automator,
expected_output="Calendário otimizado com conflitos resolvidos, intervalos e detalhes das reuniões atualizados"
)
crew = Crew(
agents=[scheduling_automator],
tasks=[automation_task]
)
crew.kickoff()
```
## Solução de Problemas
### Problemas Comuns
**Erros de Autenticação**
- Certifique-se de que sua conta Google possui as permissões necessárias para acessar o calendário
- Verifique se a conexão OAuth inclui todos os escopos necessários para a API do Google Calendar
- Confirme se as configurações de compartilhamento do calendário permitem o nível de acesso necessário
**Problemas na Criação de Eventos**
- Verifique se os formatos de horário estão corretos (ISO8601 ou timestamps Unix)
- Assegure-se de que os endereços de e-mail dos participantes estão corretamente formatados
- Verifique se o calendário de destino existe e está acessível
- Confirme se os fusos horários estão especificados corretamente
**Disponibilidade e Conflitos de Horário**
- Use formato ISO adequado para os intervalos de horário ao verificar disponibilidade
- Certifique-se de que os fusos horários estão consistentes em todas as operações
- Verifique se os IDs dos calendários estão corretos ao consultar múltiplos calendários
**Pesquisa de Contatos e Pessoas**
- Assegure-se de que os termos de pesquisa estão devidamente formatados
- Verifique se as permissões para acesso ao diretório foram concedidas
- Certifique-se de que as informações de contato estão atualizadas e acessíveis
**Atualização e Exclusão de Eventos**
- Verifique se os IDs dos eventos estão corretos e se os eventos existem
- Assegure-se de que você possui permissões de edição para os eventos
- Verifique se a propriedade do calendário permite modificações
### Obtendo Ajuda
<Card title="Precisa de ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nosso time de suporte para assistência na configuração da integração com o Google Calendar ou solução de problemas.
</Card>

321
docs/pt-BR/enterprise/integrations/google_sheets.mdx Normal file
View File

@@ -0,0 +1,321 @@
---
title: Integração com Google Sheets
description: "Sincronização de dados de planilhas com a integração do Google Sheets para CrewAI."
icon: "google"
---
## Visão Geral
Permita que seus agentes gerenciem dados de planilhas por meio do Google Sheets. Leia linhas, crie novos registros, atualize dados existentes e otimize os fluxos de trabalho de gerenciamento de dados com automação alimentada por IA. Perfeito para acompanhamento de dados, relatórios e gestão colaborativa de informações.
## Pré-requisitos
Antes de utilizar a integração com o Google Sheets, certifique-se de que você possui:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa
- Uma conta Google com acesso ao Google Sheets
- Sua conta Google conectada pela [página de integrações](https://app.crewai.com/crewai_plus/connectors)
- Planilhas com cabeçalhos de coluna adequados para operações com dados
## Configurando a Integração com Google Sheets
### 1. Conecte sua Conta Google
1. Acesse [Integrações do CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors)
2. Localize **Google Sheets** na seção Integrações de Autenticação
3. Clique em **Conectar** e conclua o fluxo OAuth
4. Conceda as permissões necessárias para acesso à planilha
5. Copie seu Token Enterprise em [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account)
### 2. Instale o Pacote Necessário
```bash
uv add crewai-tools
```
## Ações Disponíveis
<AccordionGroup>
<Accordion title="GOOGLE_SHEETS_GET_ROW">
**Descrição:** Obtém linhas de uma planilha Google Sheets.
**Parâmetros:**
- `spreadsheetId` (string, obrigatório): Planilha - Use as Configurações de Workflow do Portal de Conexão para permitir ao usuário selecionar uma planilha. Por padrão, usa a primeira worksheet da planilha selecionada.
- `limit` (string, opcional): Limite de linhas - Limita o número máximo de linhas retornadas.
</Accordion>
<Accordion title="GOOGLE_SHEETS_CREATE_ROW">
**Descrição:** Cria uma nova linha em uma planilha Google Sheets.
**Parâmetros:**
- `spreadsheetId` (string, obrigatório): Planilha - Use as Configurações de Workflow do Portal de Conexão para permitir ao usuário selecionar uma planilha. Por padrão, usa a primeira worksheet da planilha selecionada.
- `worksheet` (string, obrigatório): Worksheet - Sua worksheet deve conter cabeçalhos de coluna.
- `additionalFields` (object, obrigatório): Campos - Inclua os campos para criar essa linha como um objeto, usando os nomes das colunas como chaves. Use as Configurações de Workflow do Portal de Conexão para permitir ao usuário selecionar um Mapeamento de Colunas.
```json
{
"columnName1": "columnValue1",
"columnName2": "columnValue2",
"columnName3": "columnValue3",
"columnName4": "columnValue4"
}
```
</Accordion>
<Accordion title="GOOGLE_SHEETS_UPDATE_ROW">
**Descrição:** Atualiza linhas existentes em uma planilha Google Sheets.
**Parâmetros:**
- `spreadsheetId` (string, obrigatório): Planilha - Use as Configurações de Workflow do Portal de Conexão para permitir ao usuário selecionar uma planilha. Por padrão, usa a primeira worksheet da planilha selecionada.
- `worksheet` (string, obrigatório): Worksheet - Sua worksheet deve conter cabeçalhos de coluna.
- `filterFormula` (object, opcional): Filtro em forma normal disjuntiva - OU de grupos E (AND) de condições individuais para identificar quais linhas atualizar.
```json
{
"operator": "OR",
"conditions": [
{
"operator": "AND",
"conditions": [
{
"field": "status",
"operator": "$stringExactlyMatches",
"value": "pending"
}
]
}
]
}
```
Operadores disponíveis: `$stringContains`, `$stringDoesNotContain`, `$stringExactlyMatches`, `$stringDoesNotExactlyMatch`, `$stringStartsWith`, `$stringDoesNotStartWith`, `$stringEndsWith`, `$stringDoesNotEndWith`, `$numberGreaterThan`, `$numberLessThan`, `$numberEquals`, `$numberDoesNotEqual`, `$dateTimeAfter`, `$dateTimeBefore`, `$dateTimeEquals`, `$booleanTrue`, `$booleanFalse`, `$exists`, `$doesNotExist`
- `additionalFields` (object, obrigatório): Campos - Inclua os campos a serem atualizados como objeto, usando os nomes das colunas como chaves. Use as Configurações de Workflow do Portal de Conexão para permitir ao usuário selecionar um Mapeamento de Colunas.
```json
{
"columnName1": "newValue1",
"columnName2": "newValue2",
"columnName3": "newValue3",
"columnName4": "newValue4"
}
```
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica de um Agente Google Sheets
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Obtenha as ferramentas enterprise (ferramentas Google Sheets incluídas)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Crie um agente com capacidades para Google Sheets
sheets_agent = Agent(
role="Data Manager",
goal="Gerenciar dados de planilha e rastrear informações de maneira eficiente",
backstory="Um assistente de IA especializado em gestão de dados e operações em planilhas.",
tools=[enterprise_tools]
)
# Tarefa para adicionar novos dados a uma planilha
data_entry_task = Task(
description="Adicionar novo registro de cliente na planilha de banco de dados de clientes com nome, e-mail e data de cadastro",
agent=sheets_agent,
expected_output="Novo registro de cliente adicionado com sucesso à planilha"
)
# Execute a tarefa
crew = Crew(
agents=[sheets_agent],
tasks=[data_entry_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Específicas do Google Sheets
```python
from crewai_tools import CrewaiEnterpriseTools
# Obtenha apenas ferramentas específicas do Google Sheets
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["google_sheets_get_row", "google_sheets_create_row"]
)
data_collector = Agent(
role="Data Collector",
goal="Coletar e organizar dados em planilhas",
backstory="Um assistente de IA dedicado à coleta e organização de dados.",
tools=enterprise_tools
)
# Tarefa para coletar e organizar dados
data_collection = Task(
description="Recuperar dados atuais de inventário e adicionar novos produtos à planilha de inventário",
agent=data_collector,
expected_output="Dados de inventário recuperados e novos produtos adicionados com sucesso"
)
crew = Crew(
agents=[data_collector],
tasks=[data_collection]
)
crew.kickoff()
```
### Análise de Dados e Geração de Relatórios
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
data_analyst = Agent(
role="Data Analyst",
goal="Analisar dados de planilhas e gerar insights",
backstory="Um analista de dados experiente que extrai insights dos dados de planilhas.",
tools=[enterprise_tools]
)
# Tarefa para analisar dados e criar relatórios
analysis_task = Task(
description="""
1. Recuperar todos os dados de vendas da planilha do mês atual
2. Analisar os dados em busca de tendências e padrões
3. Criar um relatório resumo em uma nova linha com os principais indicadores
""",
agent=data_analyst,
expected_output="Dados de vendas analisados e relatório resumo criado com os principais insights"
)
crew = Crew(
agents=[data_analyst],
tasks=[analysis_task]
)
crew.kickoff()
```
### Atualizações Automatizadas de Dados
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
data_updater = Agent(
role="Data Updater",
goal="Atualizar e manter dados de planilhas automaticamente",
backstory="Um assistente de IA que mantém a precisão dos dados e atualiza registros automaticamente.",
tools=[enterprise_tools]
)
# Tarefa para atualizar dados com base em condições
update_task = Task(
description="""
1. Encontrar todos os pedidos pendentes na planilha de pedidos
2. Atualizar o status para 'processing'
3. Adicionar um registro de data/hora da atualização do status
4. Registrar as alterações em uma planilha de acompanhamento separada
""",
agent=data_updater,
expected_output="Todos os pedidos pendentes atualizados para o status processing com registros de data/hora"
)
crew = Crew(
agents=[data_updater],
tasks=[update_task]
)
crew.kickoff()
```
### Fluxo de Trabalho Complexo com Dados
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
workflow_manager = Agent(
role="Data Workflow Manager",
goal="Gerenciar fluxos de dados complexos entre várias planilhas",
backstory="Um assistente de IA que orquestra operações complexas de dados entre várias planilhas.",
tools=[enterprise_tools]
)
# Tarefa de workflow complexa
workflow_task = Task(
description="""
1. Obter todos os dados de clientes da planilha principal de clientes
2. Criar registros de resumo mensal para clientes ativos
3. Atualizar o status de clientes com base na atividade nos últimos 30 dias
4. Gerar um relatório mensal com métricas dos clientes
5. Arquivar registros de clientes inativos em uma planilha separada
""",
agent=workflow_manager,
expected_output="Workflow mensal de clientes concluído com atualizações de status e relatórios gerados"
)
crew = Crew(
agents=[workflow_manager],
tasks=[workflow_task]
)
crew.kickoff()
```
## Solução de Problemas
### Problemas Comuns
**Erros de Permissão**
- Certifique-se de que sua conta Google tem acesso de edição às planilhas alvo
- Verifique se a conexão OAuth inclui os escopos necessários para a API do Google Sheets
- Confira se as planilhas estão compartilhadas com a conta autenticada
**Problemas de Estrutura da Planilha**
- Certifique-se de que as worksheets têm cabeçalhos de coluna antes de criar ou atualizar linhas
- Verifique se os nomes das colunas em `additionalFields` correspondem exatamente aos cabeçalhos
- Confirme que a worksheet especificada existe na planilha
**Problemas de Tipo e Formato de Dados**
- Garanta que os valores dos dados estejam no formato esperado para cada coluna
- Utilize formatos de data adequados nas colunas de data (recomenda-se ISO)
- Verifique se valores numéricos estão devidamente formatados para colunas numéricas
**Problemas com Fórmulas de Filtro**
- Certifique-se de que as fórmulas de filtro seguem a estrutura JSON correta para forma normal disjuntiva
- Use nomes de campos válidos, correspondendo exatamente aos cabeçalhos das colunas
- Teste filtros simples antes de criar consultas com múltiplas condições
- Verifique se os tipos de operadores correspondem aos tipos de dados das colunas
**Limites de Linhas e Performance**
- Fique atento aos limites de linhas ao usar `GOOGLE_SHEETS_GET_ROW`
- Considere paginação para grandes volumes de dados
- Use filtros específicos para reduzir a quantidade de dados processados
**Operações de Atualização**
- Certifique-se de que as condições de filtro identifiquem corretamente as linhas a serem atualizadas
- Teste condições de filtro com pequenos conjuntos de dados antes de grandes atualizações
- Verifique se todos os campos obrigatórios estão incluídos nas operações de atualização
### Obtendo Ajuda
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nosso time de suporte para auxílio na configuração ou solução de problemas da integração com o Google Sheets.
</Card>

579
docs/pt-BR/enterprise/integrations/hubspot.mdx Normal file
View File

@@ -0,0 +1,579 @@
---
title: "Integração com HubSpot"
description: "Gerencie empresas e contatos no HubSpot com o CrewAI."
icon: "briefcase"
---
## Visão Geral
Permita que seus agentes gerenciem empresas e contatos dentro do HubSpot. Crie novos registros e otimize seus processos de CRM com automação baseada em IA.
## Pré-requisitos
Antes de utilizar a integração com o HubSpot, certifique-se de que você possui:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa.
- Uma conta HubSpot com permissões adequadas.
- Sua conta HubSpot conectada pela [página de Integrações](https://app.crewai.com/crewai_plus/connectors).
## Configurando a Integração com o HubSpot
### 1. Conecte Sua Conta HubSpot
1. Navegue até [CrewAI Enterprise Integrações](https://app.crewai.com/crewai_plus/connectors).
2. Encontre **HubSpot** na seção de Integrações de Autenticação.
3. Clique em **Conectar** e complete o fluxo OAuth.
4. Conceda as permissões necessárias para gerenciamento de empresas e contatos.
5. Copie o seu Token Enterprise nas [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account).
### 2. Instale o Pacote Necessário
```bash
uv add crewai-tools
```
## Ações Disponíveis
<AccordionGroup>
<Accordion title="HUBSPOT_CREATE_RECORD_COMPANIES">
**Descrição:** Crie um novo registro de empresa no HubSpot.
**Parâmetros:**
- `name` (string, obrigatório): Nome da empresa.
- `domain` (string, opcional): Nome do domínio da empresa.
- `industry` (string, opcional): Setor. Deve ser um dos valores predefinidos do HubSpot.
- `phone` (string, opcional): Telefone.
- `hubspot_owner_id` (string, opcional): ID do responsável pela empresa.
- `type` (string, opcional): Tipo da empresa. Valores disponíveis: `PROSPECT`, `PARTNER`, `RESELLER`, `VENDOR`, `OTHER`.
- `city` (string, opcional): Cidade.
- `state` (string, opcional): Estado/Região.
- `zip` (string, opcional): CEP.
- `numberofemployees` (number, opcional): Número de funcionários.
- `annualrevenue` (number, opcional): Receita anual.
- `timezone` (string, opcional): Fuso horário.
- `description` (string, opcional): Descrição.
- `linkedin_company_page` (string, opcional): URL da página da empresa no LinkedIn.
- `company_email` (string, opcional): E-mail da empresa.
- `first_name` (string, opcional): Nome do contato na empresa.
- `last_name` (string, opcional): Sobrenome do contato na empresa.
- `about_us` (string, opcional): Sobre nós.
- `hs_csm_sentiment` (string, opcional): Sentimento CSM. Valores disponíveis: `at_risk`, `neutral`, `healthy`.
- `closedate` (string, opcional): Data de fechamento.
- `hs_keywords` (string, opcional): Palavras-chave da empresa. Deve ser um dos valores predefinidos.
- `country` (string, opcional): País/Região.
- `hs_country_code` (string, opcional): Código do País/Região.
- `hs_employee_range` (string, opcional): Faixa de funcionários.
- `facebook_company_page` (string, opcional): URL da página da empresa no Facebook.
- `facebookfans` (number, opcional): Número de fãs no Facebook.
- `hs_gps_coordinates` (string, opcional): Coordenadas GPS.
- `hs_gps_error` (string, opcional): Erro de GPS.
- `googleplus_page` (string, opcional): URL da página do Google Plus.
- `owneremail` (string, opcional): E-mail do proprietário no HubSpot.
- `ownername` (string, opcional): Nome do proprietário no HubSpot.
- `hs_ideal_customer_profile` (string, opcional): Tier de Perfil de Cliente Ideal. Valores disponíveis: `tier_1`, `tier_2`, `tier_3`.
- `hs_industry_group` (string, opcional): Grupo do setor.
- `is_public` (boolean, opcional): É público.
- `hs_last_metered_enrichment_timestamp` (string, opcional): Último registro de enriquecimento medido.
- `hs_lead_status` (string, opcional): Status do lead. Valores disponíveis: `NEW`, `OPEN`, `IN_PROGRESS`, `OPEN_DEAL`, `UNQUALIFIED`, `ATTEMPTED_TO_CONTACT`, `CONNECTED`, `BAD_TIMING`.
- `lifecyclestage` (string, opcional): Estágio no ciclo de vida. Valores disponíveis: `subscriber`, `lead`, `marketingqualifiedlead`, `salesqualifiedlead`, `opportunity`, `customer`, `evangelist`, `other`.
- `linkedinbio` (string, opcional): Bio do LinkedIn.
- `hs_linkedin_handle` (string, opcional): Handle do LinkedIn.
- `hs_live_enrichment_deadline` (string, opcional): Prazo para enriquecimento ao vivo.
- `hs_logo_url` (string, opcional): URL do logotipo.
- `hs_analytics_source` (string, opcional): Fonte original do tráfego.
- `hs_pinned_engagement_id` (number, opcional): ID do engajamento fixado.
- `hs_quick_context` (string, opcional): Contexto rápido.
- `hs_revenue_range` (string, opcional): Faixa de receita.
- `hs_state_code` (string, opcional): Código do Estado/Região.
- `address` (string, opcional): Endereço.
- `address2` (string, opcional): Complemento de endereço.
- `hs_is_target_account` (boolean, opcional): Conta alvo.
- `hs_target_account` (string, opcional): Tier da Conta Alvo. Valores disponíveis: `tier_1`, `tier_2`, `tier_3`.
- `hs_target_account_recommendation_snooze_time` (string, opcional): Tempo para adiar recomendação de conta alvo.
- `hs_target_account_recommendation_state` (string, opcional): Estado da recomendação da conta alvo. Valores disponíveis: `DISMISSED`, `NONE`, `SNOOZED`.
- `total_money_raised` (string, opcional): Total arrecadado.
- `twitterbio` (string, opcional): Bio do Twitter.
- `twitterfollowers` (number, opcional): Seguidores no Twitter.
- `twitterhandle` (string, opcional): Usuário do Twitter.
- `web_technologies` (string, opcional): Tecnologias web utilizadas. Deve ser um dos valores predefinidos.
- `website` (string, opcional): URL do site.
- `founded_year` (string, opcional): Ano de fundação.
</Accordion>
<Accordion title="HUBSPOT_CREATE_RECORD_CONTACTS">
**Descrição:** Crie um novo registro de contato no HubSpot.
**Parâmetros:**
- `email` (string, obrigatório): E-mail do contato.
- `firstname` (string, opcional): Nome.
- `lastname` (string, opcional): Sobrenome.
- `phone` (string, opcional): Telefone.
- `hubspot_owner_id` (string, opcional): Responsável pelo contato.
- `lifecyclestage` (string, opcional): Estágio no ciclo de vida. Valores disponíveis: `subscriber`, `lead`, `marketingqualifiedlead`, `salesqualifiedlead`, `opportunity`, `customer`, `evangelist`, `other`.
- `hs_lead_status` (string, opcional): Status do lead. Valores disponíveis: `NEW`, `OPEN`, `IN_PROGRESS`, `OPEN_DEAL`, `UNQUALIFIED`, `ATTEMPTED_TO_CONTACT`, `CONNECTED`, `BAD_TIMING`.
- `annualrevenue` (string, opcional): Receita anual.
- `hs_buying_role` (string, opcional): Papel na compra.
- `cc_emails` (string, opcional): E-mails em cópia.
- `ch_customer_id` (string, opcional): ID do cliente no Chargify.
- `ch_customer_reference` (string, opcional): Referência do cliente no Chargify.
- `chargify_sites` (string, opcional): Sites Chargify.
- `city` (string, opcional): Cidade.
- `hs_facebook_ad_clicked` (boolean, opcional): Clicou em anúncio do Facebook.
- `hs_linkedin_ad_clicked` (string, opcional): Clicou em anúncio do LinkedIn.
- `hs_clicked_linkedin_ad` (string, opcional): Clicou em anúncio do LinkedIn.
- `closedate` (string, opcional): Data de fechamento.
- `company` (string, opcional): Nome da empresa.
- `company_size` (string, opcional): Tamanho da empresa.
- `country` (string, opcional): País/Região.
- `hs_country_region_code` (string, opcional): Código do País/Região.
- `date_of_birth` (string, opcional): Data de nascimento.
- `degree` (string, opcional): Grau de instrução.
- `hs_email_customer_quarantined_reason` (string, opcional): Motivo da quarentena de e-mail.
- `hs_role` (string, opcional): Cargo. Deve ser um dos valores predefinidos.
- `hs_seniority` (string, opcional): Senioridade. Deve ser um dos valores predefinidos.
- `hs_sub_role` (string, opcional): Sub papel. Deve ser um dos valores predefinidos.
- `hs_employment_change_detected_date` (string, opcional): Data da detecção de mudança de emprego.
- `hs_enriched_email_bounce_detected` (boolean, opcional): Bounce de e-mail enriquecido detectado.
- `hs_facebookid` (string, opcional): Facebook ID.
- `hs_facebook_click_id` (string, opcional): ID de clique no Facebook.
- `fax` (string, opcional): Fax.
- `field_of_study` (string, opcional): Área de estudo.
- `followercount` (number, opcional): Número de seguidores.
- `gender` (string, opcional): Gênero.
- `hs_google_click_id` (string, opcional): ID de clique no Google.
- `graduation_date` (string, opcional): Data de graduação.
- `owneremail` (string, opcional): E-mail do proprietário no HubSpot (legado).
- `ownername` (string, opcional): Nome do proprietário no HubSpot (legado).
- `industry` (string, opcional): Setor.
- `hs_inferred_language_codes` (string, opcional): Códigos de idioma inferido. Deve ser um dos valores predefinidos.
- `jobtitle` (string, opcional): Cargo.
- `hs_job_change_detected_date` (string, opcional): Data de detecção de mudança de emprego.
- `job_function` (string, opcional): Função.
- `hs_journey_stage` (string, opcional): Estágio da jornada. Deve ser um dos valores predefinidos.
- `kloutscoregeneral` (number, opcional): Klout Score.
- `hs_last_metered_enrichment_timestamp` (string, opcional): Último registro de enriquecimento medido.
- `hs_latest_source` (string, opcional): Fonte de tráfego mais recente.
- `hs_latest_source_timestamp` (string, opcional): Data da fonte mais recente.
- `hs_legal_basis` (string, opcional): Base legal para o processamento dos dados do contato.
- `linkedinbio` (string, opcional): Bio do LinkedIn.
- `linkedinconnections` (number, opcional): Conexões no LinkedIn.
- `hs_linkedin_url` (string, opcional): URL do LinkedIn.
- `hs_linkedinid` (string, opcional): Linkedin ID.
- `hs_live_enrichment_deadline` (string, opcional): Prazo para enriquecimento ao vivo.
- `marital_status` (string, opcional): Estado civil.
- `hs_content_membership_email` (string, opcional): E-mail de membro.
- `hs_content_membership_notes` (string, opcional): Notas de associação.
- `message` (string, opcional): Mensagem.
- `military_status` (string, opcional): Status militar.
- `mobilephone` (string, opcional): Celular.
- `numemployees` (string, opcional): Número de funcionários.
- `hs_analytics_source` (string, opcional): Fonte original do tráfego.
- `photo` (string, opcional): Foto.
- `hs_pinned_engagement_id` (number, opcional): ID de engajamento fixado.
- `zip` (string, opcional): CEP.
- `hs_language` (string, opcional): Idioma preferencial. Deve ser um dos valores predefinidos.
- `associatedcompanyid` (number, opcional): ID da empresa associada primária.
- `hs_email_optout_survey_reason` (string, opcional): Motivo da recusa de e-mail.
- `relationship_status` (string, opcional): Status de relacionamento.
- `hs_returning_to_office_detected_date` (string, opcional): Data de retorno ao escritório detectada.
- `salutation` (string, opcional): Saudação.
- `school` (string, opcional): Escola.
- `seniority` (string, opcional): Senioridade.
- `hs_feedback_show_nps_web_survey` (boolean, opcional): Mostrar pesquisa NPS na web.
- `start_date` (string, opcional): Data de início.
- `state` (string, opcional): Estado/Região.
- `hs_state_code` (string, opcional): Código do Estado/Região.
- `hs_content_membership_status` (string, opcional): Status.
- `address` (string, opcional): Endereço.
- `tax_exempt` (string, opcional): Isento de impostos.
- `hs_timezone` (string, opcional): Fuso horário. Deve ser um dos valores predefinidos.
- `twitterbio` (string, opcional): Bio do Twitter.
- `hs_twitterid` (string, opcional): Twitter ID.
- `twitterprofilephoto` (string, opcional): Foto de perfil do Twitter.
- `twitterhandle` (string, opcional): Usuário do Twitter.
- `vat_number` (string, opcional): Número VAT.
- `ch_verified` (string, opcional): Verificado para pagamentos ACH/eCheck.
- `website` (string, opcional): URL do site.
- `hs_whatsapp_phone_number` (string, opcional): Número do WhatsApp.
- `work_email` (string, opcional): E-mail corporativo.
- `hs_googleplusid` (string, opcional): googleplus ID.
</Accordion>
<Accordion title="HUBSPOT_CREATE_RECORD_DEALS">
**Descrição:** Crie um novo registro de negócio (deal) no HubSpot.
**Parâmetros:**
- `dealname` (string, obrigatório): Nome do negócio.
- `amount` (number, opcional): Valor do negócio.
- `dealstage` (string, opcional): Estágio no pipeline.
- `pipeline` (string, opcional): Pipeline ao qual o negócio pertence.
- `closedate` (string, opcional): Data prevista de fechamento do negócio.
- `hubspot_owner_id` (string, opcional): Responsável pelo negócio.
- `dealtype` (string, opcional): Tipo do negócio. Valores disponíveis: `newbusiness`, `existingbusiness`.
- `description` (string, opcional): Descrição do negócio.
- `hs_priority` (string, opcional): Prioridade do negócio. Valores disponíveis: `low`, `medium`, `high`.
</Accordion>
<Accordion title="HUBSPOT_CREATE_RECORD_ENGAGEMENTS">
**Descrição:** Crie um novo engajamento (ex: nota, e-mail, ligação, reunião, tarefa) no HubSpot.
**Parâmetros:**
- `engagementType` (string, obrigatório): Tipo de engajamento. Valores disponíveis: `NOTE`, `EMAIL`, `CALL`, `MEETING`, `TASK`.
- `hubspot_owner_id` (string, opcional): Usuário responsável pela atividade.
- `hs_timestamp` (string, opcional): Data e hora da atividade.
- `hs_note_body` (string, opcional): Corpo da nota. (Utilizado para `NOTE`)
- `hs_task_subject` (string, opcional): Título da tarefa. (Utilizado para `TASK`)
- `hs_task_body` (string, opcional): Notas da tarefa. (Utilizado para `TASK`)
- `hs_task_status` (string, opcional): Status da tarefa. (Utilizado para `TASK`)
- `hs_meeting_title` (string, opcional): Título da reunião. (Utilizado para `MEETING`)
- `hs_meeting_body` (string, opcional): Descrição da reunião. (Utilizado para `MEETING`)
- `hs_meeting_start_time` (string, opcional): Horário de início da reunião. (Utilizado para `MEETING`)
- `hs_meeting_end_time` (string, opcional): Horário de término da reunião. (Utilizado para `MEETING`)
</Accordion>
<Accordion title="HUBSPOT_UPDATE_RECORD_COMPANIES">
**Descrição:** Atualize um registro de empresa existente no HubSpot.
**Parâmetros:**
- `recordId` (string, obrigatório): ID da empresa a ser atualizada.
- `name` (string, opcional): Nome da empresa.
- `domain` (string, opcional): Nome do domínio da empresa.
- `industry` (string, opcional): Setor.
- `phone` (string, opcional): Telefone.
- `city` (string, opcional): Cidade.
- `state` (string, opcional): Estado/Região.
- `zip` (string, opcional): CEP.
- `numberofemployees` (number, opcional): Número de funcionários.
- `annualrevenue` (number, opcional): Receita anual.
- `description` (string, opcional): Descrição.
</Accordion>
<Accordion title="HUBSPOT_CREATE_RECORD_ANY">
**Descrição:** Crie um registro para um tipo de objeto especificado no HubSpot.
**Parâmetros:**
- `recordType` (string, obrigatório): ID do tipo de objeto personalizado.
- Parâmetros adicionais dependem do esquema do objeto personalizado.
</Accordion>
<Accordion title="HUBSPOT_UPDATE_RECORD_CONTACTS">
**Descrição:** Atualize um registro de contato existente no HubSpot.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do contato a ser atualizado.
- `firstname` (string, opcional): Nome.
- `lastname` (string, opcional): Sobrenome.
- `email` (string, opcional): E-mail.
- `phone` (string, opcional): Telefone.
- `company` (string, opcional): Nome da empresa.
- `jobtitle` (string, opcional): Cargo.
- `lifecyclestage` (string, opcional): Estágio no ciclo de vida.
</Accordion>
<Accordion title="HUBSPOT_UPDATE_RECORD_DEALS">
**Descrição:** Atualize um registro de negócio existente no HubSpot.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do negócio a ser atualizado.
- `dealname` (string, opcional): Nome do negócio.
- `amount` (number, opcional): Valor do negócio.
- `dealstage` (string, opcional): Estágio do pipeline.
- `pipeline` (string, opcional): Pipeline ao qual o negócio pertence.
- `closedate` (string, opcional): Data prevista de fechamento.
- `dealtype` (string, opcional): Tipo de negócio.
</Accordion>
<Accordion title="HUBSPOT_UPDATE_RECORD_ENGAGEMENTS">
**Descrição:** Atualize um engajamento existente no HubSpot.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do engajamento a ser atualizado.
- `hs_note_body` (string, opcional): Corpo da nota.
- `hs_task_subject` (string, opcional): Título da tarefa.
- `hs_task_body` (string, opcional): Notas da tarefa.
- `hs_task_status` (string, opcional): Status da tarefa.
</Accordion>
<Accordion title="HUBSPOT_UPDATE_RECORD_ANY">
**Descrição:** Atualize um registro para um tipo de objeto especificado no HubSpot.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do registro a ser atualizado.
- `recordType` (string, obrigatório): ID do tipo de objeto personalizado.
- Parâmetros adicionais dependem do esquema do objeto personalizado.
</Accordion>
<Accordion title="HUBSPOT_GET_RECORDS_COMPANIES">
**Descrição:** Obtenha uma lista de registros de empresas do HubSpot.
**Parâmetros:**
- `paginationParameters` (object, opcional): Use `pageCursor` para buscar páginas subsequentes.
</Accordion>
<Accordion title="HUBSPOT_GET_RECORDS_CONTACTS">
**Descrição:** Obtenha uma lista de registros de contatos do HubSpot.
**Parâmetros:**
- `paginationParameters` (object, opcional): Use `pageCursor` para buscar páginas subsequentes.
</Accordion>
<Accordion title="HUBSPOT_GET_RECORDS_DEALS">
**Descrição:** Obtenha uma lista de registros de negócios do HubSpot.
**Parâmetros:**
- `paginationParameters` (object, opcional): Use `pageCursor` para buscar páginas subsequentes.
</Accordion>
<Accordion title="HUBSPOT_GET_RECORDS_ENGAGEMENTS">
**Descrição:** Obtenha uma lista de registros de engajamentos do HubSpot.
**Parâmetros:**
- `objectName` (string, obrigatório): O tipo de engajamento a ser buscado (ex.: "notes").
- `paginationParameters` (object, opcional): Use `pageCursor` para buscar páginas subsequentes.
</Accordion>
<Accordion title="HUBSPOT_GET_RECORDS_ANY">
**Descrição:** Obtenha uma lista de registros de qualquer tipo de objeto no HubSpot.
**Parâmetros:**
- `recordType` (string, obrigatório): O ID do tipo de objeto personalizado.
- `paginationParameters` (object, opcional): Use `pageCursor` para buscar páginas subsequentes.
</Accordion>
<Accordion title="HUBSPOT_GET_RECORD_BY_ID_COMPANIES">
**Descrição:** Obtenha um registro de empresa pelo seu ID.
**Parâmetros:**
- `recordId` (string, obrigatório): ID da empresa a ser consultada.
</Accordion>
<Accordion title="HUBSPOT_GET_RECORD_BY_ID_CONTACTS">
**Descrição:** Obtenha um registro de contato pelo seu ID.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do contato a ser consultado.
</Accordion>
<Accordion title="HUBSPOT_GET_RECORD_BY_ID_DEALS">
**Descrição:** Obtenha um registro de negócio pelo seu ID.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do negócio a ser consultado.
</Accordion>
<Accordion title="HUBSPOT_GET_RECORD_BY_ID_ENGAGEMENTS">
**Descrição:** Obtenha um registro de engajamento pelo seu ID.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do engajamento a ser consultado.
</Accordion>
<Accordion title="HUBSPOT_GET_RECORD_BY_ID_ANY">
**Descrição:** Obtenha um registro de qualquer tipo de objeto especificado pelo seu ID.
**Parâmetros:**
- `recordType` (string, obrigatório): ID do tipo de objeto personalizado.
- `recordId` (string, obrigatório): ID do registro a ser consultado.
</Accordion>
<Accordion title="HUBSPOT_SEARCH_RECORDS_COMPANIES">
**Descrição:** Pesquise registros de empresas no HubSpot utilizando uma fórmula de filtro.
**Parâmetros:**
- `filterFormula` (object, opcional): Filtro em forma normal disjuntiva (OU de E).
- `paginationParameters` (object, opcional): Use `pageCursor` para buscar páginas subsequentes.
</Accordion>
<Accordion title="HUBSPOT_SEARCH_RECORDS_CONTACTS">
**Descrição:** Pesquise registros de contatos no HubSpot utilizando uma fórmula de filtro.
**Parâmetros:**
- `filterFormula` (object, opcional): Filtro em forma normal disjuntiva (OU de E).
- `paginationParameters` (object, opcional): Use `pageCursor` para buscar páginas subsequentes.
</Accordion>
<Accordion title="HUBSPOT_SEARCH_RECORDS_DEALS">
**Descrição:** Pesquise registros de negócios no HubSpot utilizando uma fórmula de filtro.
**Parâmetros:**
- `filterFormula` (object, opcional): Filtro em forma normal disjuntiva (OU de E).
- `paginationParameters` (object, opcional): Use `pageCursor` para buscar páginas subsequentes.
</Accordion>
<Accordion title="HUBSPOT_SEARCH_RECORDS_ENGAGEMENTS">
**Descrição:** Pesquise registros de engajamento no HubSpot utilizando uma fórmula de filtro.
**Parâmetros:**
- `engagementFilterFormula` (object, opcional): Filtro para engajamentos.
- `paginationParameters` (object, opcional): Use `pageCursor` para buscar páginas subsequentes.
</Accordion>
<Accordion title="HUBSPOT_SEARCH_RECORDS_ANY">
**Descrição:** Pesquise registros de qualquer tipo de objeto no HubSpot.
**Parâmetros:**
- `recordType` (string, obrigatório): O ID do tipo de objeto para pesquisa.
- `filterFormula` (string, opcional): Fórmula de filtro a aplicar.
- `paginationParameters` (object, opcional): Use `pageCursor` para buscar páginas subsequentes.
</Accordion>
<Accordion title="HUBSPOT_DELETE_RECORD_COMPANIES">
**Descrição:** Exclua um registro de empresa pelo seu ID.
**Parâmetros:**
- `recordId` (string, obrigatório): ID da empresa a ser excluída.
</Accordion>
<Accordion title="HUBSPOT_DELETE_RECORD_CONTACTS">
**Descrição:** Exclua um registro de contato pelo seu ID.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do contato a ser excluído.
</Accordion>
<Accordion title="HUBSPOT_DELETE_RECORD_DEALS">
**Descrição:** Exclua um registro de negócio pelo seu ID.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do negócio a ser excluído.
</Accordion>
<Accordion title="HUBSPOT_DELETE_RECORD_ENGAGEMENTS">
**Descrição:** Exclua um registro de engajamento pelo seu ID.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do engajamento a ser excluído.
</Accordion>
<Accordion title="HUBSPOT_DELETE_RECORD_ANY">
**Descrição:** Exclua um registro de qualquer tipo de objeto especificado pelo seu ID.
**Parâmetros:**
- `recordType` (string, obrigatório): ID do tipo de objeto personalizado.
- `recordId` (string, obrigatório): ID do registro a ser excluído.
</Accordion>
<Accordion title="HUBSPOT_GET_CONTACTS_BY_LIST_ID">
**Descrição:** Obtenha contatos de uma lista específica pelo seu ID.
**Parâmetros:**
- `listId` (string, obrigatório): ID da lista da qual obter os contatos.
- `paginationParameters` (object, opcional): Use `pageCursor` para páginas subsequentes.
</Accordion>
<Accordion title="HUBSPOT_DESCRIBE_ACTION_SCHEMA">
**Descrição:** Obtenha o esquema esperado para um dado tipo de objeto e operação.
**Parâmetros:**
- `recordType` (string, obrigatório): ID do tipo de objeto (ex.: 'companies').
- `operation` (string, obrigatório): Tipo de operação (ex.: 'CREATE_RECORD').
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica de Agente HubSpot
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Obtenha as ferramentas enterprise (ferramentas HubSpot incluídas)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Crie um agente com capacidades HubSpot
hubspot_agent = Agent(
role="CRM Manager",
goal="Manage company and contact records in HubSpot",
backstory="An AI assistant specialized in CRM management.",
tools=[enterprise_tools]
)
# Task para criar nova empresa
create_company_task = Task(
description="Create a new company in HubSpot with name 'Innovate Corp' and domain 'innovatecorp.com'.",
agent=hubspot_agent,
expected_output="Company created successfully with confirmation"
)
# Execute a tarefa
crew = Crew(
agents=[hubspot_agent],
tasks=[create_company_task]
)
crew.kickoff()
```
### Filtrando Ferramentas HubSpot Específicas
```python
from crewai_tools import CrewaiEnterpriseTools
# Obtenha somente a ferramenta para criar contatos
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["hubspot_create_record_contacts"]
)
contact_creator = Agent(
role="Contact Creator",
goal="Create new contacts in HubSpot",
backstory="An AI assistant that focuses on creating new contact entries in the CRM.",
tools=[enterprise_tools]
)
# Task para criar contato
create_contact = Task(
description="Create a new contact for 'John Doe' with email 'john.doe@example.com'.",
agent=contact_creator,
expected_output="Contact created successfully in HubSpot."
)
crew = Crew(
agents=[contact_creator],
tasks=[create_contact]
)
crew.kickoff()
```
### Gerenciamento de Contatos
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
crm_manager = Agent(
role="CRM Manager",
goal="Manage and organize HubSpot contacts efficiently.",
backstory="An experienced CRM manager who maintains an organized contact database.",
tools=[enterprise_tools]
)
# Task para gerenciar contatos
contact_task = Task(
description="Create a new contact for 'Jane Smith' at 'Global Tech Inc.' with email 'jane.smith@globaltech.com'.",
agent=crm_manager,
expected_output="Contact database updated with the new contact."
)
crew = Crew(
agents=[crm_manager],
tasks=[contact_task]
)
crew.kickoff()
```
### Precisa de Ajuda?
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para assistência na configuração ou solução de problemas com a integração HubSpot.
</Card>

394
docs/pt-BR/enterprise/integrations/jira.mdx Normal file
View File

@@ -0,0 +1,394 @@
---
title: Integração com Jira
description: "Rastreamento de problemas e gestão de projetos com a integração Jira para CrewAI."
icon: "bug"
---
## Visão Geral
Permita que seus agentes gerenciem problemas, projetos e fluxos de trabalho pelo Jira. Crie e atualize issues, acompanhe o progresso de projetos, gerencie atribuições e otimize sua gestão de projetos com automação potencializada por IA.
## Pré-requisitos
Antes de usar a integração com o Jira, certifique-se de ter:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa
- Uma conta Jira com permissões adequadas para o projeto
- Sua conta Jira conectada pela [Página de Integrações](https://app.crewai.com/crewai_plus/connectors)
## Configurando a Integração com o Jira
### 1. Conectar Sua Conta Jira
1. Acesse [Integrações CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors)
2. Encontre **Jira** na seção de Integrações de Autenticação
3. Clique em **Conectar** e complete o fluxo do OAuth
4. Conceda as permissões necessárias para gestão de issues e projetos
5. Copie seu Token Enterprise em [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account)
### 2. Instalar o Pacote Necessário
```bash
uv add crewai-tools
```
## Ações Disponíveis
<AccordionGroup>
<Accordion title="JIRA_CREATE_ISSUE">
**Descrição:** Cria uma issue no Jira.
**Parâmetros:**
- `summary` (string, obrigatório): Resumo - Um breve resumo da issue. (exemplo: "A impressora parou de funcionar").
- `project` (string, opcional): Projeto - Projeto ao qual a issue pertence. Padrão para o primeiro projeto do usuário se não informado. Use as Configurações de Workflow do Portal de Conexão para permitir a seleção de Projeto.
- `issueType` (string, opcional): Tipo de issue - Padrão para Task se não informado.
- `jiraIssueStatus` (string, opcional): Status - Padrão para o primeiro status do projeto se não informado.
- `assignee` (string, opcional): Responsável - Padrão para o usuário autenticado se não informado.
- `descriptionType` (string, opcional): Tipo de Descrição - Selecione o Tipo de Descrição.
- Opções: `description`, `descriptionJSON`
- `description` (string, opcional): Descrição - Uma descrição detalhada da issue. Este campo aparece apenas se 'descriptionType' = 'description'.
- `additionalFields` (string, opcional): Campos Adicionais - Especifique outros campos em formato JSON. Use as Configurações de Workflow do Portal de Conexão para permitir ao usuário selecionar quais campos atualizar.
```json
{
"customfield_10001": "value"
}
```
</Accordion>
<Accordion title="JIRA_UPDATE_ISSUE">
**Descrição:** Atualiza uma issue no Jira.
**Parâmetros:**
- `issueKey` (string, obrigatório): Chave da Issue (exemplo: "TEST-1234").
- `summary` (string, opcional): Resumo - Breve resumo da issue. (exemplo: "A impressora parou de funcionar").
- `issueType` (string, opcional): Tipo de issue - Use as Configurações de Workflow do Portal de Conexão para permitir a seleção.
- `jiraIssueStatus` (string, opcional): Status - Use as Configurações de Workflow do Portal de Conexão para permitir a seleção.
- `assignee` (string, opcional): Responsável - Use as Configurações de Workflow do Portal de Conexão para permitir a seleção.
- `descriptionType` (string, opcional): Tipo de Descrição - Selecione o Tipo de Descrição.
- Opções: `description`, `descriptionJSON`
- `description` (string, opcional): Descrição - Descrição detalhada da issue. Este campo aparece apenas se 'descriptionType' = 'description'.
- `additionalFields` (string, opcional): Campos Adicionais - Especifique outros campos em formato JSON.
</Accordion>
<Accordion title="JIRA_GET_ISSUE_BY_KEY">
**Descrição:** Obtém uma issue pelo identificador no Jira.
**Parâmetros:**
- `issueKey` (string, obrigatório): Chave da Issue (exemplo: "TEST-1234").
</Accordion>
<Accordion title="JIRA_FILTER_ISSUES">
**Descrição:** Busca issues no Jira usando filtros.
**Parâmetros:**
- `jqlQuery` (object, opcional): Filtro em forma normal disjuntiva - OU de grupos E de condições simples.
```json
{
"operator": "OR",
"conditions": [
{
"operator": "AND",
"conditions": [
{
"field": "status",
"operator": "$stringExactlyMatches",
"value": "Open"
}
]
}
]
}
```
Operadores disponíveis: `$stringExactlyMatches`, `$stringDoesNotExactlyMatch`, `$stringIsIn`, `$stringIsNotIn`, `$stringContains`, `$stringDoesNotContain`, `$stringGreaterThan`, `$stringLessThan`
- `limit` (string, opcional): Limitar resultados - Limite máximo de issues retornados. Padrão para 10 se estiver em branco.
</Accordion>
<Accordion title="JIRA_SEARCH_BY_JQL">
**Descrição:** Busca issues no Jira utilizando JQL.
**Parâmetros:**
- `jqlQuery` (string, obrigatório): Query JQL (exemplo: "project = PROJECT").
- `paginationParameters` (object, opcional): Parâmetros de paginação para resultados paginados.
```json
{
"pageCursor": "cursor_string"
}
```
</Accordion>
<Accordion title="JIRA_UPDATE_ISSUE_ANY">
**Descrição:** Atualiza qualquer issue no Jira. Use DESCRIBE_ACTION_SCHEMA para obter o schema de propriedades dessa função.
**Parâmetros:** Nenhum parâmetro específico - use JIRA_DESCRIBE_ACTION_SCHEMA primeiro para obter o schema esperado.
</Accordion>
<Accordion title="JIRA_DESCRIBE_ACTION_SCHEMA">
**Descrição:** Obtém o schema esperado para um tipo de issue. Use esta função caso nenhuma outra função atenda ao tipo de issue que deseja operar.
**Parâmetros:**
- `issueTypeId` (string, obrigatório): ID do Tipo de Issue.
- `projectKey` (string, obrigatório): Chave do projeto.
- `operation` (string, obrigatório): Tipo de Operação, por exemplo CREATE_ISSUE ou UPDATE_ISSUE.
</Accordion>
<Accordion title="JIRA_GET_PROJECTS">
**Descrição:** Obtém os projetos no Jira.
**Parâmetros:**
- `paginationParameters` (object, opcional): Parâmetros de Paginação.
```json
{
"pageCursor": "cursor_string"
}
```
</Accordion>
<Accordion title="JIRA_GET_ISSUE_TYPES_BY_PROJECT">
**Descrição:** Obtém os tipos de issues por projeto no Jira.
**Parâmetros:**
- `project` (string, obrigatório): Chave do projeto.
</Accordion>
<Accordion title="JIRA_GET_ISSUE_TYPES">
**Descrição:** Obtém todos os tipos de issues no Jira.
**Parâmetros:** Nenhum obrigatório.
</Accordion>
<Accordion title="JIRA_GET_ISSUE_STATUS_BY_PROJECT">
**Descrição:** Obtém os status das issues de um projeto específico.
**Parâmetros:**
- `project` (string, obrigatório): Chave do projeto.
</Accordion>
<Accordion title="JIRA_GET_ALL_ASSIGNEES_BY_PROJECT">
**Descrição:** Obtém os responsáveis por um projeto específico.
**Parâmetros:**
- `project` (string, obrigatório): Chave do projeto.
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica de um Agente Jira
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Obtenha as ferramentas enterprise (incluirá ferramentas do Jira)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Criação de um agente com capacidades Jira
jira_agent = Agent(
role="Issue Manager",
goal="Gerenciar issues do Jira e acompanhar o progresso do projeto de forma eficiente",
backstory="Um assistente de IA especializado em rastreamento de issues e gestão de projetos.",
tools=[enterprise_tools]
)
# Tarefa para criar um relatório de bug
create_bug_task = Task(
description="Criar um relatório de bug para a funcionalidade de login com alta prioridade e designar para o time de desenvolvimento",
agent=jira_agent,
expected_output="Bug report creado com sucesso e chave da issue"
)
# Executar a tarefa
crew = Crew(
agents=[jira_agent],
tasks=[create_bug_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Jira Específicas
```python
from crewai_tools import CrewaiEnterpriseTools
# Obtenha apenas ferramentas Jira específicas
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["jira_create_issue", "jira_update_issue", "jira_search_by_jql"]
)
issue_coordinator = Agent(
role="Issue Coordinator",
goal="Criar e gerenciar issues Jira de forma eficiente",
backstory="Um assistente de IA focado na criação e gestão de issues.",
tools=enterprise_tools
)
# Tarefa para gerenciar workflow de issues
issue_workflow = Task(
description="Criar uma issue de solicitação de feature e atualizar o status de issues relacionadas",
agent=issue_coordinator,
expected_output="Feature request criada e issues relacionadas atualizadas"
)
crew = Crew(
agents=[issue_coordinator],
tasks=[issue_workflow]
)
crew.kickoff()
```
### Análise e Relatórios de Projeto
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
project_analyst = Agent(
role="Project Analyst",
goal="Analisar dados de projetos e gerar insights a partir do Jira",
backstory="Um analista de projetos experiente que extrai insights de dados de gestão de projetos.",
tools=[enterprise_tools]
)
# Tarefa para analisar status do projeto
analysis_task = Task(
description="""
1. Obtenha todos os projetos e seus tipos de issues
2. Busque todas as issues abertas entre projetos
3. Analise distribuição de issues por status e responsável
4. Crie uma issue de relatório de resumo com os achados
""",
agent=project_analyst,
expected_output="Análise do projeto completa com relatório de resumo criado"
)
crew = Crew(
agents=[project_analyst],
tasks=[analysis_task]
)
crew.kickoff()
```
### Gestão Automatizada de Issues
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
automation_manager = Agent(
role="Automation Manager",
goal="Automatizar gestão de issues e processos de workflow",
backstory="Um assistente de IA que automatiza tarefas repetitivas de gestão de issues.",
tools=[enterprise_tools]
)
# Tarefa para automatizar gestão de issues
automation_task = Task(
description="""
1. Buscar todas as issues não atribuídas usando JQL
2. Obter responsáveis disponíveis de cada projeto
3. Atribuir issues automaticamente com base na carga de trabalho e especialidade
4. Atualizar prioridades das issues baseando-se na idade e tipo
5. Criar issues semanais de planejamento de sprint
""",
agent=automation_manager,
expected_output="Issues atribuídas automaticamente e issues de planejamento de sprint criadas"
)
crew = Crew(
agents=[automation_manager],
tasks=[automation_task]
)
crew.kickoff()
```
### Operações Avançadas Baseadas em Schema
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
schema_specialist = Agent(
role="Schema Specialist",
goal="Executar operações complexas no Jira usando schemas dinâmicos",
backstory="Um assistente de IA que manipula schemas dinâmicos e tipos de issues customizadas do Jira.",
tools=[enterprise_tools]
)
# Tarefa usando operações baseadas em schema
schema_task = Task(
description="""
1. Obtenha todos os projetos e seus tipos personalizados de issues
2. Para cada tipo personalizado, descreva o schema de ação
3. Crie issues usando schema dinâmico para campos complexos customizados
4. Atualize issues com valores de campos personalizados a partir de regras de negócio
""",
agent=schema_specialist,
expected_output="Issues customizadas criadas e atualizadas utilizando schemas dinâmicos"
)
crew = Crew(
agents=[schema_specialist],
tasks=[schema_task]
)
crew.kickoff()
```
## Solução de Problemas
### Problemas Comuns
**Erros de Permissão**
- Certifique-se de que sua conta Jira tem as permissões necessárias nos projetos alvo
- Verifique se a conexão OAuth inclui os escopos necessários da API Jira
- Confira se você possui permissões de criar/editar issues nos projetos especificados
**Chaves de Projeto ou Issue Inválidas**
- Confira o formato das chaves dos projetos e issues (ex: "PROJ-123")
- Verifique se os projetos existem e são acessíveis pela sua conta
- Certifique-se de que chaves de issues referenciam issues existentes
**Problemas de Tipo ou Status de Issue**
- Use JIRA_GET_ISSUE_TYPES_BY_PROJECT para obter tipos válidos de issue para um projeto
- Use JIRA_GET_ISSUE_STATUS_BY_PROJECT para obter status válidos
- Certifique-se de que tipos e status de issue estão disponíveis no projeto alvo
**Problemas com Queries JQL**
- Teste as queries JQL na busca de issues do Jira antes de utilizar em chamadas de API
- Certifique-se de que os nomes dos campos em JQL estejam corretos e existam em sua instância do Jira
- Use a sintaxe correta de JQL para queries complexas
**Problemas com Campos Customizados e Schemas**
- Use JIRA_DESCRIBE_ACTION_SCHEMA para obter o schema correto para tipos de issues complexas
- Certifique-se de que os IDs dos campos customizados estão corretos (ex: "customfield_10001")
- Verifique se esses campos estão disponíveis no projeto e tipo de issue alvo
**Problemas de Fórmulas de Filtro**
- Garanta que as fórmulas de filtro sigam a estrutura JSON correta para forma normal disjuntiva
- Use apenas campos válidos conforme configuração do seu Jira
- Teste filtros simples antes de construir queries complexas com múltiplas condições
### Obtenha Ajuda
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nosso time de suporte para obter assistência na configuração ou solução de problemas da integração Jira.
</Card>

453
docs/pt-BR/enterprise/integrations/linear.mdx Normal file
View File

@@ -0,0 +1,453 @@
---
title: Integração com o Linear
description: "Acompanhamento de projetos de software e rastreamento de bugs com a integração Linear para CrewAI."
icon: "list-check"
---
## Visão Geral
Permita que seus agentes gerenciem issues, projetos e fluxos de trabalho de desenvolvimento através do Linear. Crie e atualize issues, gerencie cronogramas de projetos, organize equipes e otimize seu processo de desenvolvimento de software com automação impulsionada por IA.
## Pré-requisitos
Antes de utilizar a integração com o Linear, certifique-se de que você possui:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com uma assinatura ativa
- Uma conta Linear com permissões apropriadas no workspace
- Conectou sua conta Linear através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
## Configurando a Integração com o Linear
### 1. Conecte sua Conta Linear
1. Navegue até [Integrações CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors)
2. Encontre **Linear** na seção Integrações de Autenticação
3. Clique em **Conectar** e complete o fluxo OAuth
4. Conceda as permissões necessárias para gerenciamento de issues e projetos
5. Copie seu Token Empresarial em [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account)
### 2. Instale o Pacote Necessário
```bash
uv add crewai-tools
```
## Ações Disponíveis
<AccordionGroup>
<Accordion title="LINEAR_CREATE_ISSUE">
**Descrição:** Crie uma nova issue no Linear.
**Parâmetros:**
- `teamId` (string, obrigatório): ID da Equipe - Especifique o ID da equipe responsável para esta nova issue. Use as Configurações de Fluxo do Connect Portal para permitir que usuários escolham um ID de Equipe. (exemplo: "a70bdf0f-530a-4887-857d-46151b52b47c").
- `title` (string, obrigatório): Título - Especifique um título para esta issue.
- `description` (string, opcional): Descrição - Especifique uma descrição para esta issue.
- `statusId` (string, opcional): Status - Especifique o status desta issue.
- `priority` (string, opcional): Prioridade - Especifique a prioridade desta issue como um inteiro.
- `dueDate` (string, opcional): Data de Vencimento - Especifique a data de vencimento desta issue no formato ISO 8601.
- `cycleId` (string, opcional): ID do Ciclo - Especifique o ciclo associado a esta issue.
- `additionalFields` (object, opcional): Campos Adicionais.
```json
{
"assigneeId": "a70bdf0f-530a-4887-857d-46151b52b47c",
"labelIds": ["a70bdf0f-530a-4887-857d-46151b52b47c"]
}
```
</Accordion>
<Accordion title="LINEAR_UPDATE_ISSUE">
**Descrição:** Atualize uma issue no Linear.
**Parâmetros:**
- `issueId` (string, obrigatório): ID da Issue - Especifique o ID da issue a ser atualizada. (exemplo: "90fbc706-18cd-42c9-ae66-6bd344cc8977").
- `title` (string, opcional): Título - Especifique um título para esta issue.
- `description` (string, opcional): Descrição - Especifique uma descrição para esta issue.
- `statusId` (string, opcional): Status - Especifique o status desta issue.
- `priority` (string, opcional): Prioridade - Especifique a prioridade desta issue como um inteiro.
- `dueDate` (string, opcional): Data de Vencimento - Especifique a data de vencimento desta issue no formato ISO 8601.
- `cycleId` (string, opcional): ID do Ciclo - Especifique o ciclo associado a esta issue.
- `additionalFields` (object, opcional): Campos Adicionais.
```json
{
"assigneeId": "a70bdf0f-530a-4887-857d-46151b52b47c",
"labelIds": ["a70bdf0f-530a-4887-857d-46151b52b47c"]
}
```
</Accordion>
<Accordion title="LINEAR_GET_ISSUE_BY_ID">
**Descrição:** Obtenha uma issue pelo ID no Linear.
**Parâmetros:**
- `issueId` (string, obrigatório): ID da Issue - Especifique o ID do registro da issue a ser buscada. (exemplo: "90fbc706-18cd-42c9-ae66-6bd344cc8977").
</Accordion>
<Accordion title="LINEAR_GET_ISSUE_BY_ISSUE_IDENTIFIER">
**Descrição:** Obtenha uma issue através do identificador da issue no Linear.
**Parâmetros:**
- `externalId` (string, obrigatório): ID Externo - Especifique o identificador legível da issue a ser buscada. (exemplo: "ABC-1").
</Accordion>
<Accordion title="LINEAR_SEARCH_ISSUE">
**Descrição:** Pesquise issues no Linear.
**Parâmetros:**
- `queryTerm` (string, obrigatório): Termo de Pesquisa - O termo a ser localizado na busca.
- `issueFilterFormula` (object, opcional): Um filtro na forma normal disjuntiva – OU de grupos E de condições únicas.
```json
{
"operator": "OR",
"conditions": [
{
"operator": "AND",
"conditions": [
{
"field": "title",
"operator": "$stringContains",
"value": "bug"
}
]
}
]
}
```
Campos disponíveis: `title`, `number`, `project`, `createdAt`
Operadores disponíveis: `$stringExactlyMatches`, `$stringDoesNotExactlyMatch`, `$stringIsIn`, `$stringIsNotIn`, `$stringStartsWith`, `$stringDoesNotStartWith`, `$stringEndsWith`, `$stringDoesNotEndWith`, `$stringContains`, `$stringDoesNotContain`, `$stringGreaterThan`, `$stringLessThan`, `$numberGreaterThanOrEqualTo`, `$numberLessThanOrEqualTo`, `$numberGreaterThan`, `$numberLessThan`, `$dateTimeAfter`, `$dateTimeBefore`
</Accordion>
<Accordion title="LINEAR_DELETE_ISSUE">
**Descrição:** Exclua uma issue no Linear.
**Parâmetros:**
- `issueId` (string, obrigatório): ID da Issue - Especifique o ID do registro da issue a ser excluída. (exemplo: "90fbc706-18cd-42c9-ae66-6bd344cc8977").
</Accordion>
<Accordion title="LINEAR_ARCHIVE_ISSUE">
**Descrição:** Arquive uma issue no Linear.
**Parâmetros:**
- `issueId` (string, obrigatório): ID da Issue - Especifique o ID do registro da issue a ser arquivada. (exemplo: "90fbc706-18cd-42c9-ae66-6bd344cc8977").
</Accordion>
<Accordion title="LINEAR_CREATE_SUB_ISSUE">
**Descrição:** Crie uma sub-issue no Linear.
**Parâmetros:**
- `parentId` (string, obrigatório): ID do Pai - Especifique o ID da issue pai desta nova issue.
- `teamId` (string, obrigatório): ID da Equipe - Especifique o ID da equipe responsável pela nova sub-issue. Use as Configurações de Fluxo do Connect Portal para permitir que usuários escolham um ID de Equipe. (exemplo: "a70bdf0f-530a-4887-857d-46151b52b47c").
- `title` (string, obrigatório): Título - Especifique um título para esta issue.
- `description` (string, opcional): Descrição - Especifique uma descrição para esta issue.
- `additionalFields` (object, opcional): Campos Adicionais.
```json
{
"lead": "linear_user_id"
}
```
</Accordion>
<Accordion title="LINEAR_CREATE_PROJECT">
**Descrição:** Crie um novo projeto no Linear.
**Parâmetros:**
- `teamIds` (object, obrigatório): ID da Equipe - Especifique o(s) ID(s) da equipe associada a este projeto como string ou array JSON. Use as Configurações de Usuário do Connect Portal para que seu usuário selecione um ID de Equipe.
```json
[
"a70bdf0f-530a-4887-857d-46151b52b47c",
"4ac7..."
]
```
- `projectName` (string, obrigatório): Nome do Projeto - Especifique o nome do projeto. (exemplo: "Meu Projeto Linear").
- `description` (string, opcional): Descrição do Projeto - Especifique uma descrição para este projeto.
- `additionalFields` (object, opcional): Campos Adicionais.
```json
{
"state": "planned",
"description": ""
}
```
</Accordion>
<Accordion title="LINEAR_UPDATE_PROJECT">
**Descrição:** Atualize um projeto no Linear.
**Parâmetros:**
- `projectId` (string, obrigatório): ID do Projeto - Especifique o ID do projeto a ser atualizado. (exemplo: "a6634484-6061-4ac7-9739-7dc5e52c796b").
- `projectName` (string, opcional): Nome do Projeto - Especifique o nome do projeto a ser atualizado. (exemplo: "Meu Projeto Linear").
- `description` (string, opcional): Descrição do Projeto - Especifique uma descrição para este projeto.
- `additionalFields` (object, opcional): Campos Adicionais.
```json
{
"state": "planned",
"description": ""
}
```
</Accordion>
<Accordion title="LINEAR_GET_PROJECT_BY_ID">
**Descrição:** Obtenha um projeto pelo ID no Linear.
**Parâmetros:**
- `projectId` (string, obrigatório): ID do Projeto - Especifique o ID do projeto a ser buscado. (exemplo: "a6634484-6061-4ac7-9739-7dc5e52c796b").
</Accordion>
<Accordion title="LINEAR_DELETE_PROJECT">
**Descrição:** Exclua um projeto no Linear.
**Parâmetros:**
- `projectId` (string, obrigatório): ID do Projeto - Especifique o ID do projeto a ser excluído. (exemplo: "a6634484-6061-4ac7-9739-7dc5e52c796b").
</Accordion>
<Accordion title="LINEAR_SEARCH_TEAMS">
**Descrição:** Pesquise equipes no Linear.
**Parâmetros:**
- `teamFilterFormula` (object, opcional): Um filtro na forma normal disjuntiva – OU de grupos E de condições únicas.
```json
{
"operator": "OR",
"conditions": [
{
"operator": "AND",
"conditions": [
{
"field": "name",
"operator": "$stringContains",
"value": "Engineering"
}
]
}
]
}
```
Campos disponíveis: `id`, `name`
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica do Agente Linear
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Obtenha ferramentas empresariais (ferramentas do Linear serão incluídas)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Crie um agente com funcionalidades do Linear
linear_agent = Agent(
role="Development Manager",
goal="Gerenciar issues do Linear e acompanhar o progresso do desenvolvimento de forma eficiente",
backstory="Um assistente de IA especializado em gerenciamento de projetos de desenvolvimento de software.",
tools=[enterprise_tools]
)
# Tarefa para criar um relatório de bug
create_bug_task = Task(
description="Crie um relatório de bug de alta prioridade para o sistema de autenticação e atribua à equipe de backend",
agent=linear_agent,
expected_output="Bug report criado com sucesso com ID da issue"
)
# Execute a tarefa
crew = Crew(
agents=[linear_agent],
tasks=[create_bug_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Lineares Específicas
```python
from crewai_tools import CrewaiEnterpriseTools
# Obtenha apenas ferramentas lineares específicas
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["linear_create_issue", "linear_update_issue", "linear_search_issue"]
)
issue_manager = Agent(
role="Issue Manager",
goal="Criar e gerenciar issues no Linear de forma eficiente",
backstory="Um assistente de IA focado na criação e no gerenciamento do ciclo de vida de issues.",
tools=enterprise_tools
)
# Tarefa para gerenciar fluxo de issues
issue_workflow = Task(
description="Crie uma issue de solicitação de recurso e atualize os status das issues relacionadas para refletir o progresso atual",
agent=issue_manager,
expected_output="Solicitação de recurso criada e issues relacionadas atualizadas"
)
crew = Crew(
agents=[issue_manager],
tasks=[issue_workflow]
)
crew.kickoff()
```
### Gerenciamento de Projetos e Equipes
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
project_coordinator = Agent(
role="Project Coordinator",
goal="Coordenar projetos e equipes no Linear de forma eficiente",
backstory="Um coordenador de projetos experiente que gerencia ciclos de desenvolvimento e fluxos de trabalho de equipe.",
tools=[enterprise_tools]
)
# Tarefa para coordenar a configuração de projeto
project_coordination = Task(
description="""
1. Pesquise por equipes de engenharia no Linear
2. Crie um novo projeto para o desenvolvimento de recursos do Q2
3. Associe o projeto às equipes relevantes
4. Crie marcos iniciais do projeto como issues
""",
agent=project_coordinator,
expected_output="Projeto Q2 criado com equipes atribuídas e marcos iniciais estabelecidos"
)
crew = Crew(
agents=[project_coordinator],
tasks=[project_coordination]
)
crew.kickoff()
```
### Hierarquia de Issues e Gerenciamento de Sub-tarefas
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
task_organizer = Agent(
role="Task Organizer",
goal="Organizar issues complexas em sub-tarefas gerenciáveis",
backstory="Um assistente de IA que divide trabalhos de desenvolvimento complexos em sub-tarefas organizadas.",
tools=[enterprise_tools]
)
# Tarefa para criar hierarquia de issues
hierarchy_task = Task(
description="""
1. Pesquise por issues de recursos grandes que precisam ser divididos
2. Para cada issue complexa, crie sub-issues para diferentes componentes
3. Atualize as issues principais com descrições adequadas e links para sub-issues
4. Atribua sub-issues aos membros apropriados da equipe com base na especialidade
""",
agent=task_organizer,
expected_output="Issues complexas divididas em sub-tarefas gerenciáveis com atribuições corretas"
)
crew = Crew(
agents=[task_organizer],
tasks=[hierarchy_task]
)
crew.kickoff()
```
### Fluxo de Trabalho de Desenvolvimento Automatizado
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
workflow_automator = Agent(
role="Workflow Automator",
goal="Automatizar processos de fluxo de trabalho de desenvolvimento no Linear",
backstory="Um assistente de IA que automatiza tarefas repetitivas de fluxo de trabalho de desenvolvimento.",
tools=[enterprise_tools]
)
# Tarefa de automação de workflow complexa
automation_task = Task(
description="""
1. Pesquise por issues que estejam em progresso há mais de 7 dias
2. Atualize suas prioridades com base nas datas de vencimento e importância do projeto
3. Crie issues semanais de planejamento de sprint para cada equipe
4. Arquive issues concluídas do ciclo anterior
5. Gere relatórios de status do projeto como novas issues
""",
agent=workflow_automator,
expected_output="Fluxo de desenvolvimento automatizado com prioridades atualizadas, planejamento de sprint e relatórios de status"
)
crew = Crew(
agents=[workflow_automator],
tasks=[automation_task]
)
crew.kickoff()
```
## Solução de Problemas
### Problemas Comuns
**Erros de Permissão**
- Certifique-se de que sua conta Linear possui as permissões necessárias no workspace de destino
- Verifique se a conexão OAuth inclui os escopos requeridos pela API do Linear
- Confirme se você tem permissões para criar/editar issues e projetos no workspace
**IDs e Referências Inválidas**
- Verifique os IDs de equipes, IDs de issues e IDs de projetos para garantir o formato UUID correto
- Assegure que as entidades referenciadas (equipes, projetos, ciclos) existem e estão acessíveis
- Verifique se os identificadores de issues seguem o formato correto (ex: "ABC-1")
**Problemas de Associação entre Equipe e Projeto**
- Use LINEAR_SEARCH_TEAMS para obter IDs de equipe válidos antes de criar issues ou projetos
- Certifique-se de que as equipes existem e estão ativas no seu workspace
- Verifique se os IDs das equipes estão devidamente formatados como UUIDs
**Problemas com Status e Prioridade das Issues**
- Verifique se os IDs de status referenciam estados de workflow válidos para a equipe
- Certifique-se de que os valores de prioridade estão dentro do intervalo válido para sua configuração do Linear
- Confirme que campos personalizados e labels existem antes de referenciá-los
**Problemas com Formato de Data e Hora**
- Use o formato ISO 8601 para datas de vencimento e timestamps
- Certifique-se de que os fusos horários estão corretos para cálculos de datas de vencimento
- Verifique se os valores de data são válidos e posteriores à data atual para datas de vencimento
**Problemas de Pesquisa e Filtros**
- Garanta que as consultas de busca estejam formatadas corretamente e não estejam vazias
- Utilize nomes de campos válidos nas fórmulas de filtro: `title`, `number`, `project`, `createdAt`
- Teste filtros simples antes de montar consultas complexas com múltiplas condições
- Verifique se os tipos de operadores correspondem aos tipos de dados dos campos filtrados
**Problemas na Criação de Sub-issues**
- Certifique-se de que os IDs das issues pai são válidos e acessíveis
- Verifique se o ID da equipe para as sub-issues corresponde ou é compatível com o da issue pai
- Assegure-se de que as issues pai não estejam arquivadas ou excluídas
### Obtendo Ajuda
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para assistência na configuração ou solução de problemas da integração com o Linear.
</Card>

509
docs/pt-BR/enterprise/integrations/notion.mdx Normal file
View File

@@ -0,0 +1,509 @@
---
title: Integração com o Notion
description: "Gerenciamento de páginas e bancos de dados com integração do Notion para o CrewAI."
icon: "book"
---
## Visão Geral
Permita que seus agentes gerenciem páginas, bancos de dados e conteúdos através do Notion. Crie e atualize páginas, gerencie blocos de conteúdo, organize bases de conhecimento e otimize seus fluxos de documentação com automação alimentada por IA.
## Pré-requisitos
Antes de usar a integração com o Notion, certifique-se de que você tem:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa
- Uma conta Notion com permissões adequadas no workspace
- Sua conta Notion conectada através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
## Configurando a Integração com o Notion
### 1. Conecte sua Conta Notion
1. Acesse [Integrações do CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors)
2. Procure por **Notion** na seção de Integrações de Autenticação
3. Clique em **Conectar** e complete o fluxo de OAuth
4. Conceda as permissões necessárias para gerenciamento de páginas e bancos de dados
5. Copie seu Token Enterprise em [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account)
### 2. Instale o Pacote Necessário
```bash
uv add crewai-tools
```
## Ações Disponíveis
<AccordionGroup>
<Accordion title="NOTION_CREATE_PAGE">
**Descrição:** Cria uma página no Notion.
**Parâmetros:**
- `parent` (object, obrigatório): Parent - A página ou banco de dados pai onde a nova página será inserida, representado como um objeto JSON com uma chave page_id ou database_id.
```json
{
"database_id": "DATABASE_ID"
}
```
- `properties` (object, obrigatório): Properties - Os valores das propriedades da página. Se o pai for um banco de dados, o schema deve corresponder às propriedades do banco de dados.
```json
{
"title": [
{
"text": {
"content": "My Page"
}
}
]
}
```
- `icon` (object, obrigatório): Icon - O ícone da página.
```json
{
"emoji": "🥬"
}
```
- `children` (object, opcional): Children - Blocos de conteúdo a serem adicionados à página.
```json
[
{
"object": "block",
"type": "heading_2",
"heading_2": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Lacinato kale"
}
}
]
}
}
]
```
- `cover` (object, opcional): Cover - A imagem de capa da página.
```json
{
"external": {
"url": "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg"
}
}
```
</Accordion>
<Accordion title="NOTION_UPDATE_PAGE">
**Descrição:** Atualiza uma página no Notion.
**Parâmetros:**
- `pageId` (string, obrigatório): Page ID - Especifique o ID da Página a ser atualizada. (exemplo: "59833787-2cf9-4fdf-8782-e53db20768a5").
- `icon` (object, obrigatório): Icon - O ícone da página.
```json
{
"emoji": "🥬"
}
```
- `archived` (boolean, opcional): Archived - Indica se a página está arquivada (excluída). Defina como true para arquivar a página. Defina como false para restaurar.
- `properties` (object, opcional): Properties - Os valores das propriedades a serem atualizados na página.
```json
{
"title": [
{
"text": {
"content": "My Updated Page"
}
}
]
}
```
- `cover` (object, opcional): Cover - A imagem de capa da página.
```json
{
"external": {
"url": "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg"
}
}
```
</Accordion>
<Accordion title="NOTION_GET_PAGE_BY_ID">
**Descrição:** Busca uma página pelo ID no Notion.
**Parâmetros:**
- `pageId` (string, obrigatório): Page ID - Especifique o ID da Página a ser buscada. (exemplo: "59833787-2cf9-4fdf-8782-e53db20768a5").
</Accordion>
<Accordion title="NOTION_ARCHIVE_PAGE">
**Descrição:** Arquiva uma página no Notion.
**Parâmetros:**
- `pageId` (string, obrigatório): Page ID - Especifique o ID da Página a ser arquivada. (exemplo: "59833787-2cf9-4fdf-8782-e53db20768a5").
</Accordion>
<Accordion title="NOTION_SEARCH_PAGES">
**Descrição:** Pesquisa páginas no Notion utilizando filtros.
**Parâmetros:**
- `searchByTitleFilterSearch` (object, opcional): Um filtro na forma normal disjuntiva - OU de grupos E de condições simples.
```json
{
"operator": "OR",
"conditions": [
{
"operator": "AND",
"conditions": [
{
"field": "query",
"operator": "$stringExactlyMatches",
"value": "meeting notes"
}
]
}
]
}
```
Campos disponíveis: `query`, `filter.value`, `direction`, `page_size`
</Accordion>
<Accordion title="NOTION_GET_PAGE_CONTENT">
**Descrição:** Obtém o conteúdo (blocos) de uma página no Notion.
**Parâmetros:**
- `blockId` (string, obrigatório): Page ID - Especifique o ID de um Bloco ou Página para receber todos os seus blocos filhos na ordem correta. (exemplo: "59833787-2cf9-4fdf-8782-e53db20768a5").
</Accordion>
<Accordion title="NOTION_UPDATE_BLOCK">
**Descrição:** Atualiza um bloco no Notion.
**Parâmetros:**
- `blockId` (string, obrigatório): Block ID - Especifique o ID do Bloco a ser atualizado. (exemplo: "9bc30ad4-9373-46a5-84ab-0a7845ee52e6").
- `archived` (boolean, opcional): Archived - Defina como true para arquivar (excluir) um bloco. Defina como false para restaurar um bloco.
- `paragraph` (object, opcional): Conteúdo do parágrafo.
```json
{
"rich_text": [
{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
}
],
"color": "default"
}
```
- `image` (object, opcional): Bloco de imagem.
```json
{
"type": "external",
"external": {
"url": "https://website.domain/images/image.png"
}
}
```
- `bookmark` (object, opcional): Bloco de bookmark.
```json
{
"caption": [],
"url": "https://companywebsite.com"
}
```
- `code` (object, opcional): Bloco de código.
```json
{
"rich_text": [
{
"type": "text",
"text": {
"content": "const a = 3"
}
}
],
"language": "javascript"
}
```
- `pdf` (object, opcional): Bloco de PDF.
```json
{
"type": "external",
"external": {
"url": "https://website.domain/files/doc.pdf"
}
}
```
- `table` (object, opcional): Bloco de Tabela.
```json
{
"table_width": 2,
"has_column_header": false,
"has_row_header": false
}
```
- `tableOfContent` (object, opcional): Bloco de Sumário.
```json
{
"color": "default"
}
```
- `additionalFields` (object, opcional): Blocos adicionais.
```json
{
"child_page": {
"title": "Lacinato kale"
},
"child_database": {
"title": "My database"
}
}
```
</Accordion>
<Accordion title="NOTION_GET_BLOCK_BY_ID">
**Descrição:** Busca um bloco pelo ID no Notion.
**Parâmetros:**
- `blockId` (string, obrigatório): Block ID - Especifique o ID do Bloco a ser buscado. (exemplo: "9bc30ad4-9373-46a5-84ab-0a7845ee52e6").
</Accordion>
<Accordion title="NOTION_DELETE_BLOCK">
**Descrição:** Exclui um bloco no Notion.
**Parâmetros:**
- `blockId` (string, obrigatório): Block ID - Especifique o ID do Bloco a ser excluído. (exemplo: "9bc30ad4-9373-46a5-84ab-0a7845ee52e6").
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica do Agente Notion
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Get enterprise tools (Notion tools will be included)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Create an agent with Notion capabilities
notion_agent = Agent(
role="Documentation Manager",
goal="Manage documentation and knowledge base in Notion efficiently",
backstory="An AI assistant specialized in content management and documentation.",
tools=[enterprise_tools]
)
# Task to create a meeting notes page
create_notes_task = Task(
description="Create a new meeting notes page in the team database with today's date and agenda items",
agent=notion_agent,
expected_output="Meeting notes page created successfully with structured content"
)
# Run the task
crew = Crew(
agents=[notion_agent],
tasks=[create_notes_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Específicas do Notion
```python
from crewai_tools import CrewaiEnterpriseTools
# Get only specific Notion tools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["notion_create_page", "notion_update_block", "notion_search_pages"]
)
content_manager = Agent(
role="Content Manager",
goal="Create and manage content pages efficiently",
backstory="An AI assistant that focuses on content creation and management.",
tools=enterprise_tools
)
# Task to manage content workflow
content_workflow = Task(
description="Create a new project documentation page and add structured content blocks for requirements and specifications",
agent=content_manager,
expected_output="Project documentation created with organized content sections"
)
crew = Crew(
agents=[content_manager],
tasks=[content_workflow]
)
crew.kickoff()
```
### Gerenciamento de Base de Conhecimento
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
knowledge_curator = Agent(
role="Knowledge Curator",
goal="Curate and organize knowledge base content in Notion",
backstory="An experienced knowledge manager who organizes and maintains comprehensive documentation.",
tools=[enterprise_tools]
)
# Task to curate knowledge base
curation_task = Task(
description="""
1. Search for existing documentation pages related to our new product feature
2. Create a comprehensive feature documentation page with proper structure
3. Add code examples, images, and links to related resources
4. Update existing pages with cross-references to the new documentation
""",
agent=knowledge_curator,
expected_output="Feature documentation created and integrated with existing knowledge base"
)
crew = Crew(
agents=[knowledge_curator],
tasks=[curation_task]
)
crew.kickoff()
```
### Estrutura e Organização de Conteúdo
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
content_organizer = Agent(
role="Content Organizer",
goal="Organize and structure content blocks for optimal readability",
backstory="An AI assistant that specializes in content structure and user experience.",
tools=[enterprise_tools]
)
# Task to organize content structure
organization_task = Task(
description="""
1. Get content from existing project pages
2. Analyze the structure and identify improvement opportunities
3. Update content blocks to use proper headings, tables, and formatting
4. Add table of contents and improve navigation between related pages
5. Create templates for future documentation consistency
""",
agent=content_organizer,
expected_output="Content reorganized with improved structure and navigation"
)
crew = Crew(
agents=[content_organizer],
tasks=[organization_task]
)
crew.kickoff()
```
### Fluxos de Trabalho de Documentação Automatizados
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
doc_automator = Agent(
role="Documentation Automator",
goal="Automate documentation workflows and maintenance",
backstory="An AI assistant that automates repetitive documentation tasks.",
tools=[enterprise_tools]
)
# Complex documentation automation task
automation_task = Task(
description="""
1. Search for pages that haven't been updated in the last 30 days
2. Review and update outdated content blocks
3. Create weekly team update pages with consistent formatting
4. Add status indicators and progress tracking to project pages
5. Generate monthly documentation health reports
6. Archive completed project pages and organize them in archive sections
""",
agent=doc_automator,
expected_output="Documentation automated with updated content, weekly reports, and organized archives"
)
crew = Crew(
agents=[doc_automator],
tasks=[automation_task]
)
crew.kickoff()
```
## Solução de Problemas
### Problemas Comuns
**Erros de Permissão**
- Certifique-se de que sua conta Notion possui acesso de edição ao workspace desejado
- Verifique se a conexão OAuth inclui os escopos necessários para a API do Notion
- Confira se as páginas e bancos de dados estão compartilhados com a integração autenticada
**IDs de Página e Bloco Inválidos**
- Revise os IDs de página e bloco para garantir que estejam no formato UUID correto
- Garanta que as páginas e blocos referenciados existem e são acessíveis
- Verifique se os IDs da página ou banco de dados pai são válidos ao criar novas páginas
**Problemas com Schema de Propriedades**
- Assegure que as propriedades da página correspondem ao schema do banco de dados ao criar páginas em bancos de dados
- Verifique se os nomes e tipos das propriedades estão corretos para o banco de dados alvo
- Confirme que as propriedades obrigatórias estão incluídas ao criar ou atualizar páginas
**Estrutura dos Blocos de Conteúdo**
- Assegure que o conteúdo dos blocos segue as especificações de rich text do Notion
- Verifique se estruturas aninhadas de blocos estão devidamente formatadas
- Confira se URLs de mídias são acessíveis e estão corretamente formatadas
**Problemas de Pesquisa e Filtros**
- Certifique-se de que as queries de pesquisa estão devidamente formatadas e não estão vazias
- Use nomes de campos válidos em fórmulas de filtro: `query`, `filter.value`, `direction`, `page_size`
- Teste pesquisas simples antes de construir condições de filtro mais complexas
**Relacionamentos Pai-Filho**
- Verifique se a página ou banco de dados pai existe antes de criar páginas filhas
- Assegure que existam permissões apropriadas para o container pai
- Confirme que os schemas do banco permitem definir as propriedades desejadas
**Rich Text e Conteúdo de Mídia**
- Assegure que URLs para imagens externas, PDFs e bookmarks sejam acessíveis
- Verifique se a formatação rich text segue as especificações da API do Notion
- Confira se os tipos de linguagem nos blocos de código são suportados pelo Notion
**Operações de Arquivamento e Exclusão**
- Entenda a diferença entre arquivar (reversível) e excluir (permanente)
- Certifique-se de ter permissões para arquivar ou excluir o conteúdo desejado
- Tenha cuidado com operações em massa que possam afetar múltiplas páginas ou blocos
### Obtendo Ajuda
<Card title="Precisa de ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nosso time de suporte para auxílio na configuração ou solução de problemas com a integração Notion.
</Card>

632
docs/pt-BR/enterprise/integrations/salesforce.mdx Normal file
View File

@@ -0,0 +1,632 @@
---
title: Integração com Salesforce
description: "Automação de vendas e CRM com integração Salesforce para CrewAI."
icon: "salesforce"
---
## Visão Geral
Permita que seus agentes gerenciem relacionamentos com clientes, processos de vendas e dados através do Salesforce. Crie e atualize registros, gerencie leads e oportunidades, execute consultas SOQL e otimize seus fluxos de trabalho de CRM com automação potencializada por IA.
## Pré-requisitos
Antes de usar a integração Salesforce, certifique-se de que você possui:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa
- Uma conta Salesforce com permissões apropriadas
- Sua conta Salesforce conectada via a [página de Integrações](https://app.crewai.com/integrations)
## Ferramentas Disponíveis
### **Gerenciamento de Registros**
<AccordionGroup>
<Accordion title="SALESFORCE_CREATE_RECORD_CONTACT">
**Descrição:** Crie um novo registro de Contato no Salesforce.
**Parâmetros:**
- `FirstName` (string, opcional): Primeiro nome
- `LastName` (string, obrigatório): Sobrenome - Este campo é obrigatório
- `accountId` (string, opcional): ID da Conta - Conta à qual o contato pertence
- `Email` (string, opcional): Endereço de e-mail
- `Title` (string, opcional): Cargo do contato, como CEO ou Vice-presidente
- `Description` (string, opcional): Descrição do contato
- `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Contato
</Accordion>
<Accordion title="SALESFORCE_CREATE_RECORD_LEAD">
**Descrição:** Crie um novo registro de Lead no Salesforce.
**Parâmetros:**
- `FirstName` (string, opcional): Primeiro nome
- `LastName` (string, obrigatório): Sobrenome - Este campo é obrigatório
- `Company` (string, obrigatório): Empresa - Este campo é obrigatório
- `Email` (string, opcional): Endereço de e-mail
- `Phone` (string, opcional): Número de telefone
- `Website` (string, opcional): URL do site
- `Title` (string, opcional): Cargo do contato, como CEO ou Vice-presidente
- `Status` (string, opcional): Status do Lead - Use as Configurações de Workflow do Connect Portal para selecionar o status do Lead
- `Description` (string, opcional): Descrição do lead
- `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Lead
</Accordion>
<Accordion title="SALESFORCE_CREATE_RECORD_OPPORTUNITY">
**Descrição:** Crie um novo registro de Oportunidade no Salesforce.
**Parâmetros:**
- `Name` (string, obrigatório): Nome da Oportunidade - Este campo é obrigatório
- `StageName` (string, opcional): Estágio da Oportunidade - Use as Configurações de Workflow do Connect Portal para selecionar o estágio
- `CloseDate` (string, opcional): Data de fechamento no formato YYYY-MM-DD - Padrão para 30 dias a partir da data atual
- `AccountId` (string, opcional): Conta à qual a Oportunidade pertence
- `Amount` (string, opcional): Valor total estimado da venda
- `Description` (string, opcional): Descrição da oportunidade
- `OwnerId` (string, opcional): Usuário Salesforce designado para esta Oportunidade
- `NextStep` (string, opcional): Descrição da próxima tarefa no fechamento da Oportunidade
- `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Oportunidade
</Accordion>
<Accordion title="SALESFORCE_CREATE_RECORD_TASK">
**Descrição:** Crie um novo registro de Tarefa no Salesforce.
**Parâmetros:**
- `whatId` (string, opcional): Relacionado ao ID - ID da Conta ou Oportunidade relacionada à Tarefa
- `whoId` (string, opcional): ID do Nome - ID do Contato ou Lead relacionado à Tarefa
- `subject` (string, obrigatório): Assunto da tarefa
- `activityDate` (string, opcional): Data da Atividade no formato YYYY-MM-DD
- `description` (string, opcional): Descrição da tarefa
- `taskSubtype` (string, obrigatório): Subtipo da Tarefa - Opções: task, email, listEmail, call
- `Status` (string, opcional): Status - Opções: Not Started, In Progress, Completed
- `ownerId` (string, opcional): ID do responsável - Usuário Salesforce designado para a Tarefa
- `callDurationInSeconds` (string, opcional): Duração da chamada em segundos
- `isReminderSet` (boolean, opcional): Se o lembrete está definido
- `reminderDateTime` (string, opcional): Data/Hora do lembrete no formato ISO
- `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Tarefa
</Accordion>
<Accordion title="SALESFORCE_CREATE_RECORD_ACCOUNT">
**Descrição:** Crie um novo registro de Conta no Salesforce.
**Parâmetros:**
- `Name` (string, obrigatório): Nome da Conta - Este campo é obrigatório
- `OwnerId` (string, opcional): Usuário Salesforce responsável por esta Conta
- `Website` (string, opcional): URL do site
- `Phone` (string, opcional): Número de telefone
- `Description` (string, opcional): Descrição da conta
- `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Conta
</Accordion>
<Accordion title="SALESFORCE_CREATE_RECORD_ANY">
**Descrição:** Crie um registro de qualquer tipo de objeto no Salesforce.
**Nota:** Esta é uma ferramenta flexível para criar registros de tipos de objetos personalizados ou desconhecidos.
</Accordion>
</AccordionGroup>
### **Atualização de Registros**
<AccordionGroup>
<Accordion title="SALESFORCE_UPDATE_RECORD_CONTACT">
**Descrição:** Atualize um registro de Contato existente no Salesforce.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do registro a ser atualizado
- `FirstName` (string, opcional): Primeiro nome
- `LastName` (string, opcional): Sobrenome
- `accountId` (string, opcional): ID da Conta à qual o contato pertence
- `Email` (string, opcional): Endereço de e-mail
- `Title` (string, opcional): Cargo do contato
- `Description` (string, opcional): Descrição do contato
- `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Contato
</Accordion>
<Accordion title="SALESFORCE_UPDATE_RECORD_LEAD">
**Descrição:** Atualize um registro de Lead existente no Salesforce.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do registro a ser atualizado
- `FirstName` (string, opcional): Primeiro nome
- `LastName` (string, opcional): Sobrenome
- `Company` (string, opcional): Nome da empresa
- `Email` (string, opcional): Endereço de e-mail
- `Phone` (string, opcional): Número de telefone
- `Website` (string, opcional): URL do site
- `Title` (string, opcional): Cargo do contato
- `Status` (string, opcional): Status do Lead
- `Description` (string, opcional): Descrição do lead
- `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Lead
</Accordion>
<Accordion title="SALESFORCE_UPDATE_RECORD_OPPORTUNITY">
**Descrição:** Atualize um registro de Oportunidade existente no Salesforce.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do registro a ser atualizado
- `Name` (string, opcional): Nome da Oportunidade
- `StageName` (string, opcional): Estágio da oportunidade
- `CloseDate` (string, opcional): Data de fechamento no formato YYYY-MM-DD
- `AccountId` (string, opcional): Conta à qual a Oportunidade pertence
- `Amount` (string, opcional): Valor total estimado da venda
- `Description` (string, opcional): Descrição da oportunidade
- `OwnerId` (string, opcional): Usuário Salesforce responsável por esta Oportunidade
- `NextStep` (string, opcional): Descrição da próxima tarefa no fechamento da Oportunidade
- `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Oportunidade
</Accordion>
<Accordion title="SALESFORCE_UPDATE_RECORD_TASK">
**Descrição:** Atualize um registro de Tarefa existente no Salesforce.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do registro a ser atualizado
- `whatId` (string, opcional): Relacionado ao ID - ID da Conta ou Oportunidade relacionada
- `whoId` (string, opcional): ID do Nome - ID do Contato ou Lead relacionado à Tarefa
- `subject` (string, opcional): Assunto da tarefa
- `activityDate` (string, opcional): Data da Atividade no formato YYYY-MM-DD
- `description` (string, opcional): Descrição da tarefa
- `Status` (string, opcional): Status - Opções: Not Started, In Progress, Completed
- `ownerId` (string, opcional): ID do responsável - Usuário Salesforce designado para a Tarefa
- `callDurationInSeconds` (string, opcional): Duração da chamada em segundos
- `isReminderSet` (boolean, opcional): Se o lembrete está definido
- `reminderDateTime` (string, opcional): Data/Hora do lembrete em formato ISO
- `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Tarefa
</Accordion>
<Accordion title="SALESFORCE_UPDATE_RECORD_ACCOUNT">
**Descrição:** Atualize um registro de Conta existente no Salesforce.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do registro a ser atualizado
- `Name` (string, opcional): Nome da Conta
- `OwnerId` (string, opcional): Usuário Salesforce responsável por esta Conta
- `Website` (string, opcional): URL do site
- `Phone` (string, opcional): Número de telefone
- `Description` (string, opcional): Descrição da conta
- `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Conta
</Accordion>
<Accordion title="SALESFORCE_UPDATE_RECORD_ANY">
**Descrição:** Atualize um registro de qualquer tipo de objeto no Salesforce.
**Nota:** Esta é uma ferramenta flexível para atualizar registros de tipos de objetos personalizados ou desconhecidos.
</Accordion>
</AccordionGroup>
### **Recuperação de Registros**
<AccordionGroup>
<Accordion title="SALESFORCE_GET_RECORD_BY_ID_CONTACT">
**Descrição:** Obtenha um registro de Contato pelo seu ID.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do registro do Contato
</Accordion>
<Accordion title="SALESFORCE_GET_RECORD_BY_ID_LEAD">
**Descrição:** Obtenha um registro de Lead pelo seu ID.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do registro do Lead
</Accordion>
<Accordion title="SALESFORCE_GET_RECORD_BY_ID_OPPORTUNITY">
**Descrição:** Obtenha um registro de Oportunidade pelo seu ID.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do registro da Oportunidade
</Accordion>
<Accordion title="SALESFORCE_GET_RECORD_BY_ID_TASK">
**Descrição:** Obtenha um registro de Tarefa pelo seu ID.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do registro da Tarefa
</Accordion>
<Accordion title="SALESFORCE_GET_RECORD_BY_ID_ACCOUNT">
**Descrição:** Obtenha um registro de Conta pelo seu ID.
**Parâmetros:**
- `recordId` (string, obrigatório): ID do registro da Conta
</Accordion>
<Accordion title="SALESFORCE_GET_RECORD_BY_ID_ANY">
**Descrição:** Obtenha um registro de qualquer tipo de objeto pelo seu ID.
**Parâmetros:**
- `recordType` (string, obrigatório): Tipo do registro (ex.: "CustomObject__c")
- `recordId` (string, obrigatório): ID do registro
</Accordion>
</AccordionGroup>
### **Busca de Registros**
<AccordionGroup>
<Accordion title="SALESFORCE_SEARCH_RECORDS_CONTACT">
**Descrição:** Pesquise registros de Contato com filtragem avançada.
**Parâmetros:**
- `filterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com operadores específicos de campo
- `sortBy` (string, opcional): Campo para ordenação (ex.: "CreatedDate")
- `sortDirection` (string, opcional): Direção da ordenação - Opções: ASC, DESC
- `includeAllFields` (boolean, opcional): Incluir todos os campos nos resultados
- `paginationParameters` (object, opcional): Configurações de paginação com pageCursor
</Accordion>
<Accordion title="SALESFORCE_SEARCH_RECORDS_LEAD">
**Descrição:** Pesquise registros de Lead com filtragem avançada.
**Parâmetros:**
- `filterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com operadores específicos de campo
- `sortBy` (string, opcional): Campo para ordenação (ex.: "CreatedDate")
- `sortDirection` (string, opcional): Direção da ordenação - Opções: ASC, DESC
- `includeAllFields` (boolean, opcional): Incluir todos os campos nos resultados
- `paginationParameters` (object, opcional): Configurações de paginação com pageCursor
</Accordion>
<Accordion title="SALESFORCE_SEARCH_RECORDS_OPPORTUNITY">
**Descrição:** Pesquise registros de Oportunidade com filtragem avançada.
**Parâmetros:**
- `filterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com operadores específicos de campo
- `sortBy` (string, opcional): Campo para ordenação (ex.: "CreatedDate")
- `sortDirection` (string, opcional): Direção da ordenação - Opções: ASC, DESC
- `includeAllFields` (boolean, opcional): Incluir todos os campos nos resultados
- `paginationParameters` (object, opcional): Configurações de paginação com pageCursor
</Accordion>
<Accordion title="SALESFORCE_SEARCH_RECORDS_TASK">
**Descrição:** Pesquise registros de Tarefa com filtragem avançada.
**Parâmetros:**
- `filterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com operadores específicos de campo
- `sortBy` (string, opcional): Campo para ordenação (ex.: "CreatedDate")
- `sortDirection` (string, opcional): Direção da ordenação - Opções: ASC, DESC
- `includeAllFields` (boolean, opcional): Incluir todos os campos nos resultados
- `paginationParameters` (object, opcional): Configurações de paginação com pageCursor
</Accordion>
<Accordion title="SALESFORCE_SEARCH_RECORDS_ACCOUNT">
**Descrição:** Pesquise registros de Conta com filtragem avançada.
**Parâmetros:**
- `filterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com operadores específicos de campo
- `sortBy` (string, opcional): Campo para ordenação (ex.: "CreatedDate")
- `sortDirection` (string, opcional): Direção da ordenação - Opções: ASC, DESC
- `includeAllFields` (boolean, opcional): Incluir todos os campos nos resultados
- `paginationParameters` (object, opcional): Configurações de paginação com pageCursor
</Accordion>
<Accordion title="SALESFORCE_SEARCH_RECORDS_ANY">
**Descrição:** Pesquise registros de qualquer tipo de objeto.
**Parâmetros:**
- `recordType` (string, obrigatório): Tipo de registro para buscar
- `filterFormula` (string, opcional): Critérios de busca por filtro
- `includeAllFields` (boolean, opcional): Incluir todos os campos nos resultados
- `paginationParameters` (object, opcional): Configurações de paginação com pageCursor
</Accordion>
</AccordionGroup>
### **Recuperação por List View**
<AccordionGroup>
<Accordion title="SALESFORCE_GET_RECORD_BY_VIEW_ID_CONTACT">
**Descrição:** Obtenha registros de Contato de um List View específico.
**Parâmetros:**
- `listViewId` (string, obrigatório): ID do List View
- `paginationParameters` (object, opcional): Configurações de paginação com pageCursor
</Accordion>
<Accordion title="SALESFORCE_GET_RECORD_BY_VIEW_ID_LEAD">
**Descrição:** Obtenha registros de Lead de um List View específico.
**Parâmetros:**
- `listViewId` (string, obrigatório): ID do List View
- `paginationParameters` (object, opcional): Configurações de paginação com pageCursor
</Accordion>
<Accordion title="SALESFORCE_GET_RECORD_BY_VIEW_ID_OPPORTUNITY">
**Descrição:** Obtenha registros de Oportunidade de um List View específico.
**Parâmetros:**
- `listViewId` (string, obrigatório): ID do List View
- `paginationParameters` (object, opcional): Configurações de paginação com pageCursor
</Accordion>
<Accordion title="SALESFORCE_GET_RECORD_BY_VIEW_ID_TASK">
**Descrição:** Obtenha registros de Tarefa de um List View específico.
**Parâmetros:**
- `listViewId` (string, obrigatório): ID do List View
- `paginationParameters` (object, opcional): Configurações de paginação com pageCursor
</Accordion>
<Accordion title="SALESFORCE_GET_RECORD_BY_VIEW_ID_ACCOUNT">
**Descrição:** Obtenha registros de Conta de um List View específico.
**Parâmetros:**
- `listViewId` (string, obrigatório): ID do List View
- `paginationParameters` (object, opcional): Configurações de paginação com pageCursor
</Accordion>
<Accordion title="SALESFORCE_GET_RECORD_BY_VIEW_ID_ANY">
**Descrição:** Obtenha registros de qualquer tipo de objeto a partir de um List View específico.
**Parâmetros:**
- `recordType` (string, obrigatório): Tipo do registro
- `listViewId` (string, obrigatório): ID do List View
- `paginationParameters` (object, opcional): Configurações de paginação com pageCursor
</Accordion>
</AccordionGroup>
### **Campos Personalizados**
<AccordionGroup>
<Accordion title="SALESFORCE_CREATE_CUSTOM_FIELD_CONTACT">
**Descrição:** Crie campos personalizados para objetos de Contato.
**Parâmetros:**
- `label` (string, obrigatório): Rótulo do campo para exibições e referência interna
- `type` (string, obrigatório): Tipo do campo - Opções: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url
- `defaultCheckboxValue` (boolean, opcional): Valor padrão para campos checkbox
- `length` (string, obrigatório): Comprimento para campos numéricos/texto
- `decimalPlace` (string, obrigatório): Casas decimais para campos numéricos
- `pickListValues` (string, obrigatório): Valores para campos picklist (separados por novas linhas)
- `visibleLines` (string, obrigatório): Linhas visíveis para campos multiseleção/área de texto
- `description` (string, opcional): Descrição do campo
- `helperText` (string, opcional): Texto de ajuda exibido ao passar o mouse
- `defaultFieldValue` (string, opcional): Valor padrão do campo
</Accordion>
<Accordion title="SALESFORCE_CREATE_CUSTOM_FIELD_LEAD">
**Descrição:** Crie campos personalizados para objetos de Lead.
**Parâmetros:**
- `label` (string, obrigatório): Rótulo do campo para exibições e referência interna
- `type` (string, obrigatório): Tipo do campo - Opções: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url
- `defaultCheckboxValue` (boolean, opcional): Valor padrão para campos checkbox
- `length` (string, obrigatório): Comprimento para campos numéricos/texto
- `decimalPlace` (string, obrigatório): Casas decimais para campos numéricos
- `pickListValues` (string, obrigatório): Valores para campos picklist (separados por novas linhas)
- `visibleLines` (string, obrigatório): Linhas visíveis para campos multiseleção/área de texto
- `description` (string, opcional): Descrição do campo
- `helperText` (string, opcional): Texto de ajuda exibido ao passar o mouse
- `defaultFieldValue` (string, opcional): Valor padrão do campo
</Accordion>
<Accordion title="SALESFORCE_CREATE_CUSTOM_FIELD_OPPORTUNITY">
**Descrição:** Crie campos personalizados para objetos de Oportunidade.
**Parâmetros:**
- `label` (string, obrigatório): Rótulo do campo para exibições e referência interna
- `type` (string, obrigatório): Tipo do campo - Opções: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url
- `defaultCheckboxValue` (boolean, opcional): Valor padrão para campos checkbox
- `length` (string, obrigatório): Comprimento para campos numéricos/texto
- `decimalPlace` (string, obrigatório): Casas decimais para campos numéricos
- `pickListValues` (string, obrigatório): Valores para campos picklist (separados por novas linhas)
- `visibleLines` (string, obrigatório): Linhas visíveis para campos multiseleção/área de texto
- `description` (string, opcional): Descrição do campo
- `helperText` (string, opcional): Texto de ajuda exibido ao passar o mouse
- `defaultFieldValue` (string, opcional): Valor padrão do campo
</Accordion>
<Accordion title="SALESFORCE_CREATE_CUSTOM_FIELD_TASK">
**Descrição:** Crie campos personalizados para objetos de Tarefa.
**Parâmetros:**
- `label` (string, obrigatório): Rótulo do campo para exibições e referência interna
- `type` (string, obrigatório): Tipo do campo - Opções: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, Time, Url
- `defaultCheckboxValue` (boolean, opcional): Valor padrão para campos checkbox
- `length` (string, obrigatório): Comprimento para campos numéricos/texto
- `decimalPlace` (string, obrigatório): Casas decimais para campos numéricos
- `pickListValues` (string, obrigatório): Valores para campos picklist (separados por novas linhas)
- `visibleLines` (string, obrigatório): Linhas visíveis para campos multiseleção
- `description` (string, opcional): Descrição do campo
- `helperText` (string, opcional): Texto de ajuda exibido ao passar o mouse
- `defaultFieldValue` (string, opcional): Valor padrão do campo
</Accordion>
<Accordion title="SALESFORCE_CREATE_CUSTOM_FIELD_ACCOUNT">
**Descrição:** Crie campos personalizados para objetos de Conta.
**Parâmetros:**
- `label` (string, obrigatório): Rótulo do campo para exibições e referência interna
- `type` (string, obrigatório): Tipo do campo - Opções: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url
- `defaultCheckboxValue` (boolean, opcional): Valor padrão para campos checkbox
- `length` (string, obrigatório): Comprimento para campos numéricos/texto
- `decimalPlace` (string, obrigatório): Casas decimais para campos numéricos
- `pickListValues` (string, obrigatório): Valores para campos picklist (separados por novas linhas)
- `visibleLines` (string, obrigatório): Linhas visíveis para campos multiseleção/área de texto
- `description` (string, opcional): Descrição do campo
- `helperText` (string, opcional): Texto de ajuda exibido ao passar o mouse
- `defaultFieldValue` (string, opcional): Valor padrão do campo
</Accordion>
<Accordion title="SALESFORCE_CREATE_CUSTOM_FIELD_ANY">
**Descrição:** Crie campos personalizados para qualquer tipo de objeto.
**Nota:** Esta é uma ferramenta flexível para criar campos personalizados para tipos de objetos personalizados ou desconhecidos.
</Accordion>
</AccordionGroup>
### **Operações Avançadas**
<AccordionGroup>
<Accordion title="SALESFORCE_WRITE_SOQL_QUERY">
**Descrição:** Execute consultas SOQL personalizadas em seus dados do Salesforce.
**Parâmetros:**
- `query` (string, obrigatório): Consulta SOQL (ex.: "SELECT Id, Name FROM Account WHERE Name = 'Exemplo'")
</Accordion>
<Accordion title="SALESFORCE_CREATE_CUSTOM_OBJECT">
**Descrição:** Crie um novo objeto personalizado no Salesforce.
**Parâmetros:**
- `label` (string, obrigatório): Rótulo do objeto para abas, layouts de página e relatórios
- `pluralLabel` (string, obrigatório): Rótulo plural (ex.: "Contas")
- `description` (string, opcional): Uma descrição do Objeto Personalizado
- `recordName` (string, obrigatório): Nome do registro exibido em layouts e buscas (ex.: "Nome da Conta")
</Accordion>
<Accordion title="SALESFORCE_DESCRIBE_ACTION_SCHEMA">
**Descrição:** Obtenha o schema esperado para operações em tipos de objetos específicos.
**Parâmetros:**
- `recordType` (string, obrigatório): Tipo de registro a ser detalhado
- `operation` (string, obrigatório): Tipo de Operação (ex.: "CREATE_RECORD" ou "UPDATE_RECORD")
**Nota:** Use esta função primeiro ao trabalhar com objetos personalizados para entender seu schema antes de realizar operações.
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica de um Agente Salesforce
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Obtenha ferramentas enterprise (ferramentas Salesforce serão incluídas)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Crie um agente com capacidades Salesforce
salesforce_agent = Agent(
role="CRM Manager",
goal="Manage customer relationships and sales processes efficiently",
backstory="An AI assistant specialized in CRM operations and sales automation.",
tools=[enterprise_tools]
)
# Task to create a new lead
create_lead_task = Task(
description="Create a new lead for John Doe from Example Corp with email john.doe@example.com",
agent=salesforce_agent,
expected_output="Lead created successfully with lead ID"
)
# Run the task
crew = Crew(
agents=[salesforce_agent],
tasks=[create_lead_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Salesforce Específicas
```python
from crewai_tools import CrewaiEnterpriseTools
# Obtenha apenas ferramentas Salesforce específicas
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["salesforce_create_record_lead", "salesforce_update_record_opportunity", "salesforce_search_records_contact"]
)
sales_manager = Agent(
role="Sales Manager",
goal="Manage leads and opportunities in the sales pipeline",
backstory="An experienced sales manager who handles lead qualification and opportunity management.",
tools=enterprise_tools
)
# Task to manage sales pipeline
pipeline_task = Task(
description="Create a qualified lead and convert it to an opportunity with $50,000 value",
agent=sales_manager,
expected_output="Lead created and opportunity established successfully"
)
crew = Crew(
agents=[sales_manager],
tasks=[pipeline_task]
)
crew.kickoff()
```
### Gerenciamento de Contatos e Contas
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
account_manager = Agent(
role="Account Manager",
goal="Manage customer accounts and maintain strong relationships",
backstory="An AI assistant that specializes in account management and customer relationship building.",
tools=[enterprise_tools]
)
# Task to manage customer accounts
account_task = Task(
description="""
1. Create a new account for TechCorp Inc.
2. Add John Doe as the primary contact for this account
3. Create a follow-up task for next week to check on their project status
""",
agent=account_manager,
expected_output="Account, contact, and follow-up task created successfully"
)
crew = Crew(
agents=[account_manager],
tasks=[account_task]
)
crew.kickoff()
```
### Consultas SOQL Avançadas e Relatórios
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
data_analyst = Agent(
role="Sales Data Analyst",
goal="Generate insights from Salesforce data using SOQL queries",
backstory="An analytical AI that excels at extracting meaningful insights from CRM data.",
tools=[enterprise_tools]
)
# Complex task involving SOQL queries and data analysis
analysis_task = Task(
description="""
1. Execute a SOQL query to find all opportunities closing this quarter
2. Search for contacts at companies with opportunities over $100K
3. Create a summary report of the sales pipeline status
4. Update high-value opportunities with next steps
""",
agent=data_analyst,
expected_output="Comprehensive sales pipeline analysis with actionable insights"
)
crew = Crew(
agents=[data_analyst],
tasks=[analysis_task]
)
crew.kickoff()
```
Esta documentação abrangente cobre todas as ferramentas Salesforce organizadas por funcionalidade, facilitando que os usuários encontrem as operações específicas de que necessitam para automação de seu CRM.
### Precisa de ajuda?
<Card title="Precisa de ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para assistência na configuração da integração com Salesforce ou para resolução de problemas.
</Card>

382
docs/pt-BR/enterprise/integrations/shopify.mdx Normal file
View File

@@ -0,0 +1,382 @@
---
title: Integração com Shopify
description: "Gestão de e-commerce e loja online com integração do Shopify para CrewAI."
icon: "shopify"
---
## Visão Geral
Permita que seus agentes gerenciem operações de e-commerce através do Shopify. Gerencie clientes, pedidos, produtos, inventário e análises da loja para otimizar sua empresa online com automação alimentada por IA.
## Pré-requisitos
Antes de utilizar a integração com o Shopify, certifique-se de que você possui:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com uma assinatura ativa
- Uma loja Shopify com permissões administrativas adequadas
- Sua loja Shopify conectada através da [página de Integrações](https://app.crewai.com/integrations)
## Ferramentas Disponíveis
### **Gerenciamento de Clientes**
<AccordionGroup>
<Accordion title="SHOPIFY_GET_CUSTOMERS">
**Descrição:** Recupera uma lista de clientes da sua loja Shopify.
**Parâmetros:**
- `customerIds` (string, opcional): Lista de IDs de clientes separada por vírgula para filtrar (exemplo: "207119551, 207119552")
- `createdAtMin` (string, opcional): Retorna somente clientes criados após esta data (ISO ou timestamp Unix)
- `createdAtMax` (string, opcional): Retorna somente clientes criados antes desta data (ISO ou timestamp Unix)
- `updatedAtMin` (string, opcional): Retorna somente clientes atualizados após esta data (ISO ou timestamp Unix)
- `updatedAtMax` (string, opcional): Retorna somente clientes atualizados antes desta data (ISO ou timestamp Unix)
- `limit` (string, opcional): Número máximo de clientes a retornar (padrão 250)
</Accordion>
<Accordion title="SHOPIFY_SEARCH_CUSTOMERS">
**Descrição:** Pesquise por clientes usando critérios de filtragem avançados.
**Parâmetros:**
- `filterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com operadores específicos de campo
- `limit` (string, opcional): Número máximo de clientes a retornar (padrão 250)
</Accordion>
<Accordion title="SHOPIFY_CREATE_CUSTOMER">
**Descrição:** Crie um novo cliente em sua loja Shopify.
**Parâmetros:**
- `firstName` (string, obrigatório): Primeiro nome do cliente
- `lastName` (string, obrigatório): Sobrenome do cliente
- `email` (string, obrigatório): Endereço de e-mail do cliente
- `company` (string, opcional): Nome da empresa
- `streetAddressLine1` (string, opcional): Endereço
- `streetAddressLine2` (string, opcional): Complemento do endereço
- `city` (string, opcional): Cidade
- `state` (string, opcional): Estado ou código da província
- `country` (string, opcional): País
- `zipCode` (string, opcional): CEP
- `phone` (string, opcional): Telefone
- `tags` (string, opcional): Tags como array ou lista separada por vírgula
- `note` (string, opcional): Observação sobre o cliente
- `sendEmailInvite` (boolean, opcional): Se deve enviar convite por e-mail
- `metafields` (object, opcional): Metacampos adicionais em formato JSON
</Accordion>
<Accordion title="SHOPIFY_UPDATE_CUSTOMER">
**Descrição:** Atualize um cliente existente em sua loja Shopify.
**Parâmetros:**
- `customerId` (string, obrigatório): O ID do cliente a ser atualizado
- `firstName` (string, opcional): Primeiro nome do cliente
- `lastName` (string, opcional): Sobrenome do cliente
- `email` (string, opcional): Endereço de e-mail do cliente
- `company` (string, opcional): Nome da empresa
- `streetAddressLine1` (string, opcional): Endereço
- `streetAddressLine2` (string, opcional): Complemento do endereço
- `city` (string, opcional): Cidade
- `state` (string, opcional): Estado ou código da província
- `country` (string, opcional): País
- `zipCode` (string, opcional): CEP
- `phone` (string, opcional): Telefone
- `tags` (string, opcional): Tags como array ou lista separada por vírgula
- `note` (string, opcional): Observação sobre o cliente
- `sendEmailInvite` (boolean, opcional): Se deve enviar convite por e-mail
- `metafields` (object, opcional): Metacampos adicionais em formato JSON
</Accordion>
</AccordionGroup>
### **Gestão de Pedidos**
<AccordionGroup>
<Accordion title="SHOPIFY_GET_ORDERS">
**Descrição:** Recupera uma lista de pedidos da sua loja Shopify.
**Parâmetros:**
- `orderIds` (string, opcional): Lista de IDs de pedidos separada por vírgula para filtrar (exemplo: "450789469, 450789470")
- `createdAtMin` (string, opcional): Retorna somente pedidos criados após esta data (ISO ou timestamp Unix)
- `createdAtMax` (string, opcional): Retorna somente pedidos criados antes desta data (ISO ou timestamp Unix)
- `updatedAtMin` (string, opcional): Retorna somente pedidos atualizados após esta data (ISO ou timestamp Unix)
- `updatedAtMax` (string, opcional): Retorna somente pedidos atualizados antes desta data (ISO ou timestamp Unix)
- `limit` (string, opcional): Número máximo de pedidos a retornar (padrão 250)
</Accordion>
<Accordion title="SHOPIFY_CREATE_ORDER">
**Descrição:** Crie um novo pedido em sua loja Shopify.
**Parâmetros:**
- `email` (string, obrigatório): Endereço de e-mail do cliente
- `lineItems` (object, obrigatório): Itens do pedido em formato JSON com título, preço, quantidade e variant_id
- `sendReceipt` (boolean, opcional): Se deve enviar recibo do pedido
- `fulfillmentStatus` (string, opcional): Status de atendimento - Opções: fulfilled, null, partial, restocked
- `financialStatus` (string, opcional): Status financeiro - Opções: pending, authorized, partially_paid, paid, partially_refunded, refunded, voided
- `inventoryBehaviour` (string, opcional): Comportamento de inventário - Opções: bypass, decrement_ignoring_policy, decrement_obeying_policy
- `note` (string, opcional): Observação do pedido
</Accordion>
<Accordion title="SHOPIFY_UPDATE_ORDER">
**Descrição:** Atualize um pedido existente em sua loja Shopify.
**Parâmetros:**
- `orderId` (string, obrigatório): O ID do pedido a ser atualizado
- `email` (string, opcional): Endereço de e-mail do cliente
- `lineItems` (object, opcional): Itens do pedido atualizados em formato JSON
- `sendReceipt` (boolean, opcional): Se deve enviar recibo do pedido
- `fulfillmentStatus` (string, opcional): Status de atendimento - Opções: fulfilled, null, partial, restocked
- `financialStatus` (string, opcional): Status financeiro - Opções: pending, authorized, partially_paid, paid, partially_refunded, refunded, voided
- `inventoryBehaviour` (string, opcional): Comportamento de inventário - Opções: bypass, decrement_ignoring_policy, decrement_obeying_policy
- `note` (string, opcional): Observação do pedido
</Accordion>
<Accordion title="SHOPIFY_GET_ABANDONED_CARTS">
**Descrição:** Recupera carrinhos abandonados da sua loja Shopify.
**Parâmetros:**
- `createdWithInLast` (string, opcional): Restringe os resultados para checkouts criados dentro do período especificado
- `createdAfterId` (string, opcional): Restringe os resultados após o ID especificado
- `status` (string, opcional): Mostra checkouts com o status especificado - Opções: open, closed (padrão open)
- `createdAtMin` (string, opcional): Retorna somente carrinhos criados após esta data (ISO ou timestamp Unix)
- `createdAtMax` (string, opcional): Retorna somente carrinhos criados antes desta data (ISO ou timestamp Unix)
- `limit` (string, opcional): Número máximo de carrinhos a retornar (padrão 250)
</Accordion>
</AccordionGroup>
### **Gestão de Produtos (REST API)**
<AccordionGroup>
<Accordion title="SHOPIFY_GET_PRODUCTS">
**Descrição:** Recupera uma lista de produtos da sua loja Shopify utilizando a REST API.
**Parâmetros:**
- `productIds` (string, opcional): Lista de IDs de produtos separada por vírgula para filtrar (exemplo: "632910392, 632910393")
- `title` (string, opcional): Filtrar pelo título do produto
- `productType` (string, opcional): Filtrar pelo tipo de produto
- `vendor` (string, opcional): Filtrar por fornecedor
- `status` (string, opcional): Filtrar por status - Opções: active, archived, draft
- `createdAtMin` (string, opcional): Retorna somente produtos criados após esta data (ISO ou timestamp Unix)
- `createdAtMax` (string, opcional): Retorna somente produtos criados antes desta data (ISO ou timestamp Unix)
- `updatedAtMin` (string, opcional): Retorna somente produtos atualizados após esta data (ISO ou timestamp Unix)
- `updatedAtMax` (string, opcional): Retorna somente produtos atualizados antes desta data (ISO ou timestamp Unix)
- `limit` (string, opcional): Número máximo de produtos a retornar (padrão 250)
</Accordion>
<Accordion title="SHOPIFY_CREATE_PRODUCT">
**Descrição:** Crie um novo produto em sua loja Shopify utilizando a REST API.
**Parâmetros:**
- `title` (string, obrigatório): Título do produto
- `productType` (string, obrigatório): Tipo/categoria do produto
- `vendor` (string, obrigatório): Fornecedor do produto
- `productDescription` (string, opcional): Descrição do produto (aceita texto simples ou HTML)
- `tags` (string, opcional): Tags do produto como array ou lista separada por vírgula
- `price` (string, opcional): Preço do produto
- `inventoryPolicy` (string, opcional): Política de estoque - Opções: deny, continue
- `imageUrl` (string, opcional): URL da imagem do produto
- `isPublished` (boolean, opcional): Se o produto está publicado
- `publishToPointToSale` (boolean, opcional): Se deve publicar no ponto de venda
</Accordion>
<Accordion title="SHOPIFY_UPDATE_PRODUCT">
**Descrição:** Atualize um produto existente em sua loja Shopify utilizando a REST API.
**Parâmetros:**
- `productId` (string, obrigatório): O ID do produto a ser atualizado
- `title` (string, opcional): Título do produto
- `productType` (string, opcional): Tipo/categoria do produto
- `vendor` (string, opcional): Fornecedor do produto
- `productDescription` (string, opcional): Descrição do produto (aceita texto simples ou HTML)
- `tags` (string, opcional): Tags do produto como array ou lista separada por vírgula
- `price` (string, opcional): Preço do produto
- `inventoryPolicy` (string, opcional): Política de estoque - Opções: deny, continue
- `imageUrl` (string, opcional): URL da imagem do produto
- `isPublished` (boolean, opcional): Se o produto está publicado
- `publishToPointToSale` (boolean, opcional): Se deve publicar no ponto de venda
</Accordion>
</AccordionGroup>
### **Gestão de Produtos (GraphQL)**
<AccordionGroup>
<Accordion title="SHOPIFY_GET_PRODUCTS_GRAPHQL">
**Descrição:** Recupere produtos utilizando filtros avançados do GraphQL.
**Parâmetros:**
- `productFilterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com suporte a campos como id, title, vendor, status, handle, tag, created_at, updated_at, published_at
</Accordion>
<Accordion title="SHOPIFY_CREATE_PRODUCT_GRAPHQL">
**Descrição:** Crie um novo produto utilizando a API GraphQL com suporte aprimorado a mídias.
**Parâmetros:**
- `title` (string, obrigatório): Título do produto
- `productType` (string, obrigatório): Tipo/categoria do produto
- `vendor` (string, obrigatório): Fornecedor do produto
- `productDescription` (string, opcional): Descrição do produto (aceita texto simples ou HTML)
- `tags` (string, opcional): Tags do produto como array ou lista separada por vírgula
- `media` (object, opcional): Objetos de mídia com texto alternativo, tipo de conteúdo e URL de origem
- `additionalFields` (object, opcional): Campos adicionais do produto como status, requiresSellingPlan, giftCard
</Accordion>
<Accordion title="SHOPIFY_UPDATE_PRODUCT_GRAPHQL">
**Descrição:** Atualize um produto existente utilizando a API GraphQL com suporte aprimorado a mídias.
**Parâmetros:**
- `productId` (string, obrigatório): O ID GraphQL do produto a ser atualizado (ex.: "gid://shopify/Product/913144112")
- `title` (string, opcional): Título do produto
- `productType` (string, opcional): Tipo/categoria do produto
- `vendor` (string, opcional): Fornecedor do produto
- `productDescription` (string, opcional): Descrição do produto (aceita texto simples ou HTML)
- `tags` (string, opcional): Tags do produto como array ou lista separada por vírgula
- `media` (object, opcional): Objetos de mídia atualizados com texto alternativo, tipo de conteúdo e URL de origem
- `additionalFields` (object, opcional): Campos adicionais do produto como status, requiresSellingPlan, giftCard
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica do Agente Shopify
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Get enterprise tools (Shopify tools will be included)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Create an agent with Shopify capabilities
shopify_agent = Agent(
role="E-commerce Manager",
goal="Manage online store operations and customer relationships efficiently",
backstory="An AI assistant specialized in e-commerce operations and online store management.",
tools=[enterprise_tools]
)
# Task to create a new customer
create_customer_task = Task(
description="Create a new VIP customer Jane Smith with email jane.smith@example.com and phone +1-555-0123",
agent=shopify_agent,
expected_output="Customer created successfully with customer ID"
)
# Run the task
crew = Crew(
agents=[shopify_agent],
tasks=[create_customer_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Específicas do Shopify
```python
from crewai_tools import CrewaiEnterpriseTools
# Get only specific Shopify tools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["shopify_create_customer", "shopify_create_order", "shopify_get_products"]
)
store_manager = Agent(
role="Store Manager",
goal="Manage customer orders and product catalog",
backstory="An experienced store manager who handles customer relationships and inventory management.",
tools=enterprise_tools
)
# Task to manage store operations
store_task = Task(
description="Create a new customer and process their order for 2 Premium Coffee Mugs",
agent=store_manager,
expected_output="Customer created and order processed successfully"
)
crew = Crew(
agents=[store_manager],
tasks=[store_task]
)
crew.kickoff()
```
### Gestão de Produtos com GraphQL
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
product_manager = Agent(
role="Product Manager",
goal="Manage product catalog and inventory with advanced GraphQL capabilities",
backstory="An AI assistant that specializes in product management and catalog optimization.",
tools=[enterprise_tools]
)
# Task to manage product catalog
catalog_task = Task(
description="""
1. Create a new product "Premium Coffee Mug" from Coffee Co vendor
2. Add high-quality product images and descriptions
3. Search for similar products from the same vendor
4. Update product tags and pricing strategy
""",
agent=product_manager,
expected_output="Product created and catalog optimized successfully"
)
crew = Crew(
agents=[product_manager],
tasks=[catalog_task]
)
crew.kickoff()
```
### Análise de Pedidos e Clientes
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
analytics_agent = Agent(
role="E-commerce Analyst",
goal="Analyze customer behavior and order patterns to optimize store performance",
backstory="An analytical AI that excels at extracting insights from e-commerce data.",
tools=[enterprise_tools]
)
# Complex task involving multiple operations
analytics_task = Task(
description="""
1. Retrieve recent customer data and order history
2. Identify abandoned carts from the last 7 days
3. Analyze product performance and inventory levels
4. Generate recommendations for customer retention
""",
agent=analytics_agent,
expected_output="Comprehensive e-commerce analytics report with actionable insights"
)
crew = Crew(
agents=[analytics_agent],
tasks=[analytics_task]
)
crew.kickoff()
```
### Precisa de Ajuda?
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para assistência na configuração ou resolução de problemas de integração com o Shopify.
</Card>

293
docs/pt-BR/enterprise/integrations/slack.mdx Normal file
View File

@@ -0,0 +1,293 @@
---
title: Integração com Slack
description: "Comunicação e colaboração em equipe com a integração Slack para CrewAI."
icon: "slack"
---
## Visão Geral
Permita que seus agentes gerenciem a comunicação da equipe pelo Slack. Envie mensagens, pesquise conversas, gerencie canais e coordene as atividades do time para otimizar os fluxos de colaboração com automação impulsionada por IA.
## Pré-requisitos
Antes de usar a integração com o Slack, certifique-se de que você tenha:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa
- Um workspace do Slack com permissões apropriadas
- Seu workspace do Slack conectado por meio da [página de Integrações](https://app.crewai.com/integrations)
## Ferramentas Disponíveis
### **Gerenciamento de Usuários**
<AccordionGroup>
<Accordion title="SLACK_LIST_MEMBERS">
**Descrição:** Lista todos os membros de um canal do Slack.
**Parâmetros:**
- Nenhum parâmetro necessário – recupera todos os membros do canal
</Accordion>
<Accordion title="SLACK_GET_USER_BY_EMAIL">
**Descrição:** Encontre um usuário no seu workspace do Slack pelo endereço de e-mail.
**Parâmetros:**
- `email` (string, obrigatório): O endereço de e-mail de um usuário do workspace
</Accordion>
<Accordion title="SLACK_GET_USERS_BY_NAME">
**Descrição:** Pesquise usuários pelo nome ou nome de exibição.
**Parâmetros:**
- `name` (string, obrigatório): Nome real do usuário para a pesquisa
- `displayName` (string, obrigatório): Nome de exibição do usuário para a pesquisa
- `paginationParameters` (object, opcional): Configurações de paginação
- `pageCursor` (string, opcional): Cursor de página para paginação
</Accordion>
</AccordionGroup>
### **Gerenciamento de Canais**
<AccordionGroup>
<Accordion title="SLACK_LIST_CHANNELS">
**Descrição:** Lista todos os canais do seu workspace no Slack.
**Parâmetros:**
- Nenhum parâmetro necessário – recupera todos os canais acessíveis
</Accordion>
</AccordionGroup>
### **Mensagens**
<AccordionGroup>
<Accordion title="SLACK_SEND_MESSAGE">
**Descrição:** Envie uma mensagem para um canal do Slack.
**Parâmetros:**
- `channel` (string, obrigatório): Nome ou ID do canal – Use as Configurações de Workflow do Connect Portal para que usuários selecionem o canal, ou insira o nome do canal para criar um novo
- `message` (string, obrigatório): Texto da mensagem a ser enviada
- `botName` (string, obrigatório): Nome do bot que enviará a mensagem
- `botIcon` (string, obrigatório): Ícone do bot – Pode ser uma URL de imagem ou um emoji (ex.: ":dog:")
- `blocks` (object, opcional): JSON do Slack Block Kit para mensagens ricas com anexos e elementos interativos
- `authenticatedUser` (boolean, opcional): Se verdadeiro, a mensagem aparecerá como enviada pelo seu usuário autenticado do Slack ao invés do aplicativo (por padrão é falso)
</Accordion>
<Accordion title="SLACK_SEND_DIRECT_MESSAGE">
**Descrição:** Envie uma mensagem direta para um usuário específico no Slack.
**Parâmetros:**
- `memberId` (string, obrigatório): ID do usuário destinatário – Use as Configurações de Workflow do Connect Portal para que usuários selecionem um membro
- `message` (string, obrigatório): Texto da mensagem a ser enviada
- `botName` (string, obrigatório): Nome do bot que enviará a mensagem
- `botIcon` (string, obrigatório): Ícone do bot – Pode ser uma URL de imagem ou um emoji (ex.: ":dog:")
- `blocks` (object, opcional): JSON do Slack Block Kit para formatação rica com anexos e elementos interativos
- `authenticatedUser` (boolean, opcional): Se verdadeiro, a mensagem aparecerá como enviada pelo seu usuário autenticado do Slack (padrão é falso)
</Accordion>
</AccordionGroup>
### **Pesquisa & Descoberta**
<AccordionGroup>
<Accordion title="SLACK_SEARCH_MESSAGES">
**Descrição:** Procure por mensagens em todo o seu workspace do Slack.
**Parâmetros:**
- `query` (string, obrigatório): Consulta de pesquisa usando a sintaxe do Slack para encontrar mensagens que correspondam aos critérios especificados
**Exemplos de Consultas de Pesquisa:**
- `"project update"` – Busca mensagens contendo "project update"
- `from:@john in:#general` – Busca mensagens do John no canal #general
- `has:link after:2023-01-01` – Busca mensagens com links após 1º de janeiro de 2023
- `in:@channel before:yesterday` – Busca mensagens em um canal específico antes de ontem
</Accordion>
</AccordionGroup>
## Integração com Block Kit
O Block Kit do Slack permite criar mensagens ricas e interativas. Veja alguns exemplos de como usar o parâmetro `blocks`:
### Texto Simples com Anexo
```json
[
{
"text": "I am a test message",
"attachments": [
{
"text": "And here's an attachment!"
}
]
}
]
```
### Formatação Rica com Seções
```json
[
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Project Update*\nStatus: ✅ Complete"
}
},
{
"type": "divider"
},
{
"type": "section",
"text": {
"type": "plain_text",
"text": "All tasks have been completed successfully."
}
}
]
```
## Exemplos de Uso
### Configuração Básica de Agente Slack
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Get enterprise tools (Slack tools will be included)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Create an agent with Slack capabilities
slack_agent = Agent(
role="Team Communication Manager",
goal="Facilitate team communication and coordinate collaboration efficiently",
backstory="An AI assistant specialized in team communication and workspace coordination.",
tools=[enterprise_tools]
)
# Task to send project updates
update_task = Task(
description="Send a project status update to the #general channel with current progress",
agent=slack_agent,
expected_output="Project update message sent successfully to team channel"
)
# Run the task
crew = Crew(
agents=[slack_agent],
tasks=[update_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Específicas do Slack
```python
from crewai_tools import CrewaiEnterpriseTools
# Get only specific Slack tools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["slack_send_message", "slack_send_direct_message", "slack_search_messages"]
)
communication_manager = Agent(
role="Communication Coordinator",
goal="Manage team communications and ensure important messages reach the right people",
backstory="An experienced communication coordinator who handles team messaging and notifications.",
tools=enterprise_tools
)
# Task to coordinate team communication
coordination_task = Task(
description="Send task completion notifications to team members and update project channels",
agent=communication_manager,
expected_output="Team notifications sent and project channels updated successfully"
)
crew = Crew(
agents=[communication_manager],
tasks=[coordination_task]
)
crew.kickoff()
```
### Mensagens Avançadas com Block Kit
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
notification_agent = Agent(
role="Notification Manager",
goal="Create rich, interactive notifications and manage workspace communication",
backstory="An AI assistant that specializes in creating engaging team notifications and updates.",
tools=[enterprise_tools]
)
# Task to send rich notifications
notification_task = Task(
description="""
1. Send a formatted project completion message to #general with progress charts
2. Send direct messages to team leads with task summaries
3. Create interactive notification with action buttons for team feedback
""",
agent=notification_agent,
expected_output="Rich notifications sent with interactive elements and formatted content"
)
crew = Crew(
agents=[notification_agent],
tasks=[notification_task]
)
crew.kickoff()
```
### Pesquisa de Mensagens e Análises
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
analytics_agent = Agent(
role="Communication Analyst",
goal="Analyze team communication patterns and extract insights from conversations",
backstory="An analytical AI that excels at understanding team dynamics through communication data.",
tools=[enterprise_tools]
)
# Complex task involving search and analysis
analysis_task = Task(
description="""
1. Search for recent project-related messages across all channels
2. Find users by email to identify team members
3. Analyze communication patterns and response times
4. Generate weekly team communication summary
""",
agent=analytics_agent,
expected_output="Comprehensive communication analysis with team insights and recommendations"
)
crew = Crew(
agents=[analytics_agent],
tasks=[analysis_task]
)
crew.kickoff()
```
## Fale com o Suporte
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
Entre em contato com nossa equipe de suporte para obter ajuda na configuração ou solução de problemas da integração com o Slack.
</Card>

305
docs/pt-BR/enterprise/integrations/stripe.mdx Normal file
View File

@@ -0,0 +1,305 @@
---
title: Integração Stripe
description: "Processamento de pagamentos e gerenciamento de assinaturas com integração Stripe para CrewAI."
icon: "stripe"
---
## Visão Geral
Permita que seus agentes gerenciem pagamentos, assinaturas e faturamento de clientes através do Stripe. Gerencie dados de clientes, processe assinaturas, gerencie produtos e acompanhe transações financeiras para otimizar seus fluxos de pagamento com automação impulsionada por IA.
## Pré-requisitos
Antes de usar a integração com o Stripe, certifique-se de que você tem:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com uma assinatura ativa
- Uma conta Stripe com permissões apropriadas de API
- Sua conta Stripe conectada através da [página de Integrações](https://app.crewai.com/integrations)
## Ferramentas Disponíveis
### **Gerenciamento de Clientes**
<AccordionGroup>
<Accordion title="STRIPE_CREATE_CUSTOMER">
**Descrição:** Crie um novo cliente em sua conta Stripe.
**Parâmetros:**
- `emailCreateCustomer` (string, obrigatório): Endereço de e-mail do cliente
- `name` (string, opcional): Nome completo do cliente
- `description` (string, opcional): Descrição do cliente para referência interna
- `metadataCreateCustomer` (objeto, opcional): Metadados adicionais como pares chave-valor (exemplo: `{"field1": 1, "field2": 2}`)
</Accordion>
<Accordion title="STRIPE_GET_CUSTOMER_BY_ID">
**Descrição:** Recupera um cliente específico pelo ID do cliente Stripe.
**Parâmetros:**
- `idGetCustomer` (string, obrigatório): O ID do cliente Stripe a ser recuperado
</Accordion>
<Accordion title="STRIPE_GET_CUSTOMERS">
**Descrição:** Recupera uma lista de clientes com filtragem opcional.
**Parâmetros:**
- `emailGetCustomers` (string, opcional): Filtra clientes pelo endereço de e-mail
- `createdAfter` (string, opcional): Filtra clientes criados após esta data (timestamp Unix)
- `createdBefore` (string, opcional): Filtra clientes criados antes desta data (timestamp Unix)
- `limitGetCustomers` (string, opcional): Número máximo de clientes a retornar (padrão: 10)
</Accordion>
<Accordion title="STRIPE_UPDATE_CUSTOMER">
**Descrição:** Atualiza as informações de um cliente existente.
**Parâmetros:**
- `customerId` (string, obrigatório): O ID do cliente a ser atualizado
- `emailUpdateCustomer` (string, opcional): Novo endereço de e-mail
- `name` (string, opcional): Novo nome do cliente
- `description` (string, opcional): Nova descrição do cliente
- `metadataUpdateCustomer` (objeto, opcional): Novos metadados como pares chave-valor
</Accordion>
</AccordionGroup>
### **Gerenciamento de Assinaturas**
<AccordionGroup>
<Accordion title="STRIPE_CREATE_SUBSCRIPTION">
**Descrição:** Cria uma nova assinatura para um cliente.
**Parâmetros:**
- `customerIdCreateSubscription` (string, obrigatório): O ID do cliente para o qual a assinatura será criada
- `plan` (string, obrigatório): O ID do plano para assinatura - Use as Configurações do Workflow do Portal Connect para permitir que usuários selecionem um plano
- `metadataCreateSubscription` (objeto, opcional): Metadados adicionais para a assinatura
</Accordion>
<Accordion title="STRIPE_GET_SUBSCRIPTIONS">
**Descrição:** Recupera assinaturas com filtragem opcional.
**Parâmetros:**
- `customerIdGetSubscriptions` (string, opcional): Filtra assinaturas por ID do cliente
- `subscriptionStatus` (string, opcional): Filtra por status da assinatura - Opções: incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid
- `limitGetSubscriptions` (string, opcional): Número máximo de assinaturas a retornar (padrão: 10)
</Accordion>
</AccordionGroup>
### **Gerenciamento de Produtos**
<AccordionGroup>
<Accordion title="STRIPE_CREATE_PRODUCT">
**Descrição:** Cria um novo produto no seu catálogo Stripe.
**Parâmetros:**
- `productName` (string, obrigatório): Nome do produto
- `description` (string, opcional): Descrição do produto
- `metadataProduct` (objeto, opcional): Metadados adicionais do produto como pares chave-valor
</Accordion>
<Accordion title="STRIPE_GET_PRODUCT_BY_ID">
**Descrição:** Recupera um produto específico pelo ID do produto Stripe.
**Parâmetros:**
- `productId` (string, obrigatório): O ID do produto Stripe a ser recuperado
</Accordion>
<Accordion title="STRIPE_GET_PRODUCTS">
**Descrição:** Recupera uma lista de produtos com filtragem opcional.
**Parâmetros:**
- `createdAfter` (string, opcional): Filtra produtos criados após esta data (timestamp Unix)
- `createdBefore` (string, opcional): Filtra produtos criados antes desta data (timestamp Unix)
- `limitGetProducts` (string, opcional): Número máximo de produtos a retornar (padrão: 10)
</Accordion>
</AccordionGroup>
### **Operações Financeiras**
<AccordionGroup>
<Accordion title="STRIPE_GET_BALANCE_TRANSACTIONS">
**Descrição:** Recupera transações de saldo da sua conta Stripe.
**Parâmetros:**
- `balanceTransactionType` (string, opcional): Filtra por tipo de transação - Opções: charge, refund, payment, payment_refund
- `paginationParameters` (objeto, opcional): Configurações de paginação
- `pageCursor` (string, opcional): Cursor da página para paginação
</Accordion>
<Accordion title="STRIPE_GET_PLANS">
**Descrição:** Recupera planos de assinatura da sua conta Stripe.
**Parâmetros:**
- `isPlanActive` (boolean, opcional): Filtra por status do plano - true para planos ativos, false para inativos
- `paginationParameters` (objeto, opcional): Configurações de paginação
- `pageCursor` (string, opcional): Cursor da página para paginação
</Accordion>
</AccordionGroup>
## Exemplos de Uso
### Configuração Básica do Agente Stripe
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Get enterprise tools (Stripe tools will be included)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Create an agent with Stripe capabilities
stripe_agent = Agent(
role="Payment Manager",
goal="Manage customer payments, subscriptions, and billing operations efficiently",
backstory="An AI assistant specialized in payment processing and subscription management.",
tools=[enterprise_tools]
)
# Task to create a new customer
create_customer_task = Task(
description="Create a new premium customer John Doe with email john.doe@example.com",
agent=stripe_agent,
expected_output="Customer created successfully with customer ID"
)
# Run the task
crew = Crew(
agents=[stripe_agent],
tasks=[create_customer_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Stripe Específicas
```python
from crewai_tools import CrewaiEnterpriseTools
# Get only specific Stripe tools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["stripe_create_customer", "stripe_create_subscription", "stripe_get_balance_transactions"]
)
billing_manager = Agent(
role="Billing Manager",
goal="Handle customer billing, subscriptions, and payment processing",
backstory="An experienced billing manager who handles subscription lifecycle and payment operations.",
tools=enterprise_tools
)
# Task to manage billing operations
billing_task = Task(
description="Create a new customer and set up their premium subscription plan",
agent=billing_manager,
expected_output="Customer created and subscription activated successfully"
)
crew = Crew(
agents=[billing_manager],
tasks=[billing_task]
)
crew.kickoff()
```
### Gerenciamento de Assinaturas
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
subscription_manager = Agent(
role="Subscription Manager",
goal="Manage customer subscriptions and optimize recurring revenue",
backstory="An AI assistant that specializes in subscription lifecycle management and customer retention.",
tools=[enterprise_tools]
)
# Task to manage subscription operations
subscription_task = Task(
description="""
1. Create a new product "Premium Service Plan" with advanced features
2. Set up subscription plans with different tiers
3. Create customers and assign them to appropriate plans
4. Monitor subscription status and handle billing issues
""",
agent=subscription_manager,
expected_output="Subscription management system configured with customers and active plans"
)
crew = Crew(
agents=[subscription_manager],
tasks=[subscription_task]
)
crew.kickoff()
```
### Análises e Relatórios Financeiros
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
financial_analyst = Agent(
role="Financial Analyst",
goal="Analyze payment data and generate financial insights",
backstory="An analytical AI that excels at extracting insights from payment and subscription data.",
tools=[enterprise_tools]
)
# Complex task involving financial analysis
analytics_task = Task(
description="""
1. Retrieve balance transactions for the current month
2. Analyze customer payment patterns and subscription trends
3. Identify high-value customers and subscription performance
4. Generate monthly financial performance report
""",
agent=financial_analyst,
expected_output="Comprehensive financial analysis with payment insights and recommendations"
)
crew = Crew(
agents=[financial_analyst],
tasks=[analytics_task]
)
crew.kickoff()
```
## Referência de Status de Assinatura
Compreendendo os status de assinaturas:
- **incomplete** - A assinatura requer método de pagamento ou confirmação de pagamento
- **incomplete_expired** - A assinatura expirou antes da confirmação do pagamento
- **trialing** - A assinatura está em período de avaliação
- **active** - A assinatura está ativa e em dia
- **past_due** - O pagamento falhou mas a assinatura ainda está ativa
- **canceled** - A assinatura foi cancelada
- **unpaid** - O pagamento falhou e a assinatura não está mais ativa
## Uso de Metadados
Os metadados permitem que você armazene informações adicionais sobre clientes, assinaturas e produtos:
```json
{
"customer_segment": "enterprise",
"acquisition_source": "google_ads",
"lifetime_value": "high",
"custom_field_1": "value1"
}
```
Esta integração permite uma automação abrangente do gerenciamento de pagamentos e assinaturas, possibilitando que seus agentes de IA administrem operações de faturamento perfeitamente dentro do seu ecossistema Stripe.

343
docs/pt-BR/enterprise/integrations/zendesk.mdx Normal file
View File

@@ -0,0 +1,343 @@
---
title: Integração com Zendesk
description: "Gestão de suporte ao cliente e helpdesk com integração Zendesk para CrewAI."
icon: "headset"
---
## Visão Geral
Permita que seus agentes gerenciem operações de suporte ao cliente através do Zendesk. Crie e atualize tickets, gerencie usuários, monitore métricas de suporte e otimize seus fluxos de atendimento ao cliente com automação impulsionada por IA.
## Pré-requisitos
Antes de usar a integração com o Zendesk, certifique-se de que você possui:
- Uma conta [CrewAI Enterprise](https://app.crewai.com) com uma assinatura ativa
- Uma conta Zendesk com permissões apropriadas de API
- Sua conta Zendesk conectada através da [página de Integrações](https://app.crewai.com/integrations)
## Ferramentas Disponíveis
### **Gerenciamento de Tickets**
<AccordionGroup>
<Accordion title="ZENDESK_CREATE_TICKET">
**Descrição:** Crie um novo ticket de suporte no Zendesk.
**Parâmetros:**
- `ticketSubject` (string, obrigatório): Assunto do ticket (ex.: "Socorro, minha impressora está pegando fogo!")
- `ticketDescription` (string, obrigatório): Primeiro comentário que aparece no ticket (ex.: "A fumaça é muito colorida.")
- `requesterName` (string, obrigatório): Nome do usuário solicitando suporte (ex.: "Jane Cliente")
- `requesterEmail` (string, obrigatório): E-mail do solicitante do suporte (ex.: "jane@example.com")
- `assigneeId` (string, opcional): ID do agente Zendesk atribuído ao ticket - Use as Configurações de Fluxo de Trabalho do Portal Connect para permitir a seleção do responsável
- `ticketType` (string, opcional): Tipo de ticket - Opções: problem, incident, question, task
- `ticketPriority` (string, opcional): Nível de prioridade - Opções: urgent, high, normal, low
- `ticketStatus` (string, opcional): Status do ticket - Opções: new, open, pending, hold, solved, closed
- `ticketDueAt` (string, opcional): Data de vencimento para tickets do tipo tarefa (timestamp ISO 8601)
- `ticketTags` (string, opcional): Array de tags a aplicar (ex.: `["enterprise", "outra_tag"]`)
- `ticketExternalId` (string, opcional): ID externo para vincular tickets a registros locais
- `ticketCustomFields` (object, opcional): Valores de campos personalizados em formato JSON
</Accordion>
<Accordion title="ZENDESK_UPDATE_TICKET">
**Descrição:** Atualize um ticket de suporte existente no Zendesk.
**Parâmetros:**
- `ticketId` (string, obrigatório): ID do ticket a ser atualizado (ex.: "35436")
- `ticketSubject` (string, opcional): Assunto atualizado do ticket
- `requesterName` (string, obrigatório): Nome do solicitante deste ticket
- `requesterEmail` (string, obrigatório): E-mail do solicitante deste ticket
- `assigneeId` (string, opcional): ID atualizado do responsável - Use as Configurações de Fluxo de Trabalho do Portal Connect
- `ticketType` (string, opcional): Tipo atualizado - Opções: problem, incident, question, task
- `ticketPriority` (string, opcional): Prioridade atualizada - Opções: urgent, high, normal, low
- `ticketStatus` (string, opcional): Status atualizado - Opções: new, open, pending, hold, solved, closed
- `ticketDueAt` (string, opcional): Nova data de vencimento (timestamp ISO 8601)
- `ticketTags` (string, opcional): Array de tags atualizadas
- `ticketExternalId` (string, opcional): Novo ID externo
- `ticketCustomFields` (object, opcional): Valores atualizados dos campos personalizados
</Accordion>
<Accordion title="ZENDESK_GET_TICKET_BY_ID">
**Descrição:** Recupere um ticket específico pelo ID.
**Parâmetros:**
- `ticketId` (string, obrigatório): ID do ticket a ser recuperado (ex.: "35436")
</Accordion>
<Accordion title="ZENDESK_ADD_COMMENT_TO_TICKET">
**Descrição:** Adicione um comentário ou nota interna a um ticket existente.
**Parâmetros:**
- `ticketId` (string, obrigatório): ID do ticket para adicionar o comentário (ex.: "35436")
- `commentBody` (string, obrigatório): Mensagem do comentário (aceita texto simples ou HTML, ex.: "Obrigado pela sua ajuda!")
- `isInternalNote` (boolean, opcional): Defina como verdadeiro para notas internas ao invés de respostas públicas (padrão é falso)
- `isPublic` (boolean, opcional): Verdadeiro para comentários públicos, falso para notas internas
</Accordion>
<Accordion title="ZENDESK_SEARCH_TICKETS">
**Descrição:** Busque tickets usando diversos filtros e critérios.
**Parâmetros:**
- `ticketSubject` (string, opcional): Filtrar pelo texto no assunto do ticket
- `ticketDescription` (string, opcional): Filtrar por texto na descrição e comentários do ticket
- `ticketStatus` (string, opcional): Filtrar por status - Opções: new, open, pending, hold, solved, closed
- `ticketType` (string, opcional): Filtrar por tipo - Opções: problem, incident, question, task, no_type
- `ticketPriority` (string, opcional): Filtrar por prioridade - Opções: urgent, high, normal, low, no_priority
- `requesterId` (string, opcional): Filtrar por ID do solicitante
- `assigneeId` (string, opcional): Filtrar pelo ID do agente responsável
- `recipientEmail` (string, opcional): Filtrar pelo e-mail do destinatário original
- `ticketTags` (string, opcional): Filtrar por tags do ticket
- `ticketExternalId` (string, opcional): Filtrar por ID externo
- `createdDate` (object, opcional): Filtrar por data de criação com operador (EQUALS, LESS_THAN_EQUALS, GREATER_THAN_EQUALS) e valor
- `updatedDate` (object, opcional): Filtrar por data de atualização com operador e valor
- `dueDate` (object, opcional): Filtrar por data de vencimento com operador e valor
- `sort_by` (string, opcional): Campo de ordenação - Opções: created_at, updated_at, priority, status, ticket_type
- `sort_order` (string, opcional): Direção da ordenação - Opções: asc, desc
</Accordion>
</AccordionGroup>
### **Gerenciamento de Usuários**
<AccordionGroup>
<Accordion title="ZENDESK_CREATE_USER">
**Descrição:** Crie um novo usuário no Zendesk.
**Parâmetros:**
- `name` (string, obrigatório): Nome completo do usuário
- `email` (string, opcional): E-mail do usuário (ex.: "jane@example.com")
- `phone` (string, opcional): Telefone do usuário
- `role` (string, opcional): Papel do usuário - Opções: admin, agent, end-user
- `externalId` (string, opcional): Identificador único de outro sistema
- `details` (string, opcional): Detalhes adicionais do usuário
- `notes` (string, opcional): Notas internas sobre o usuário
</Accordion>
<Accordion title="ZENDESK_UPDATE_USER">
**Descrição:** Atualize informações de um usuário existente.
**Parâmetros:**
- `userId` (string, obrigatório): ID do usuário a ser atualizado
- `name` (string, opcional): Nome atualizado do usuário
- `email` (string, opcional): Novo e-mail (adicionado como e-mail secundário na atualização)
- `phone` (string, opcional): Novo telefone
- `role` (string, opcional): Novo papel - Opções: admin, agent, end-user
- `externalId` (string, opcional): Novo ID externo
- `details` (string, opcional): Novos detalhes do usuário
- `notes` (string, opcional): Novas notas internas
</Accordion>
<Accordion title="ZENDESK_GET_USER_BY_ID">
**Descrição:** Recupere um usuário específico pelo ID.
**Parâmetros:**
- `userId` (string, obrigatório): ID do usuário a ser recuperado
</Accordion>
<Accordion title="ZENDESK_SEARCH_USERS">
**Descrição:** Busque usuários utilizando vários critérios.
**Parâmetros:**
- `name` (string, opcional): Filtrar por nome do usuário
- `email` (string, opcional): Filtrar por e-mail do usuário (ex.: "jane@example.com")
- `role` (string, opcional): Filtrar por papel - Opções: admin, agent, end-user
- `externalId` (string, opcional): Filtrar por ID externo
- `sort_by` (string, opcional): Campo de ordenação - Opções: created_at, updated_at
- `sort_order` (string, opcional): Direção de ordenação - Opções: asc, desc
</Accordion>
</AccordionGroup>
### **Ferramentas Administrativas**
<AccordionGroup>
<Accordion title="ZENDESK_GET_TICKET_FIELDS">
**Descrição:** Recupere todos os campos padrão e personalizados disponíveis para tickets.
**Parâmetros:**
- `paginationParameters` (object, opcional): Configurações de paginação
- `pageCursor` (string, opcional): Cursor de página para paginação
</Accordion>
<Accordion title="ZENDESK_GET_TICKET_AUDITS">
**Descrição:** Obtenha registros de auditoria (histórico somente leitura) dos tickets.
**Parâmetros:**
- `ticketId` (string, opcional): Obtenha auditorias para um ticket específico (se vazio, recupera auditorias de todos os tickets não arquivados, ex.: "1234")
- `paginationParameters` (object, opcional): Configurações de paginação
- `pageCursor` (string, opcional): Cursor de página para paginação
</Accordion>
</AccordionGroup>
## Campos Personalizados
Campos personalizados permitem armazenar informações adicionais específicas para sua organização:
```json
[
{ "id": 27642, "value": "745" },
{ "id": 27648, "value": "yes" }
]
```
## Níveis de Prioridade dos Tickets
Compreendendo os níveis de prioridade:
- **urgent** - Questões críticas que exigem atenção imediata
- **high** - Questões importantes que devem ser tratadas rapidamente
- **normal** - Prioridade padrão para a maioria dos tickets
- **low** - Questões menores que podem ser tratadas quando conveniente
## Fluxo de Status dos Tickets
Progresso padrão de status dos tickets:
- **new** - Recém-criado, ainda não atribuído
- **open** - Em andamento
- **pending** - Aguardando resposta do cliente ou ação externa
- **hold** - Pausa temporária
- **solved** - Problema resolvido, aguardando confirmação do cliente
- **closed** - Ticket finalizado e fechado
## Exemplos de Uso
### Configuração Básica de Agente Zendesk
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
# Obtenha as ferramentas enterprise (as ferramentas Zendesk serão incluídas)
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
# Crie um agente com capacidades Zendesk
zendesk_agent = Agent(
role="Gerente de Suporte",
goal="Gerenciar tickets de suporte ao cliente e oferecer excelente atendimento",
backstory="Um assistente de IA especializado em operações de suporte ao cliente e gerenciamento de tickets.",
tools=[enterprise_tools]
)
# Tarefa para criar um novo ticket de suporte
create_ticket_task = Task(
description="Crie um ticket de suporte de alta prioridade para John Smith que não consegue acessar sua conta após redefinir a senha",
agent=zendesk_agent,
expected_output="Ticket de suporte criado com sucesso com o ID do ticket"
)
# Execute a tarefa
crew = Crew(
agents=[zendesk_agent],
tasks=[create_ticket_task]
)
crew.kickoff()
```
### Filtrando Ferramentas Zendesk Específicas
```python
from crewai_tools import CrewaiEnterpriseTools
# Obtenha apenas ferramentas Zendesk específicas
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token",
actions_list=["zendesk_create_ticket", "zendesk_update_ticket", "zendesk_add_comment_to_ticket"]
)
support_agent = Agent(
role="Agente de Suporte ao Cliente",
goal="Atender consultas de clientes e resolver issues de suporte de forma eficiente",
backstory="Um agente de suporte experiente que se especializa em resolução de tickets e comunicação com clientes.",
tools=enterprise_tools
)
# Tarefa para gerenciar o fluxo de suporte
support_task = Task(
description="Crie um ticket para problemas de login, adicione comentários de troubleshooting e atualize o status para resolvido",
agent=support_agent,
expected_output="Ticket de suporte gerenciado através de todo o fluxo de resolução"
)
crew = Crew(
agents=[support_agent],
tasks=[support_task]
)
crew.kickoff()
```
### Gerenciamento Avançado de Tickets
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
ticket_manager = Agent(
role="Gerente de Tickets",
goal="Gerenciar fluxos de tickets de suporte e garantir resolução tempestiva",
backstory="Um assistente de IA que se especializa em triagem de tickets de suporte e otimização de fluxos de trabalho.",
tools=[enterprise_tools]
)
# Tarefa para gerenciar o ciclo de vida do ticket
ticket_workflow = Task(
description="""
1. Crie um novo ticket de suporte para problemas de acesso à conta
2. Adicione notas internas com as etapas de troubleshooting
3. Atualize a prioridade do ticket de acordo com o nível do cliente
4. Adicione comentários de resolução e feche o ticket
""",
agent=ticket_manager,
expected_output="Ciclo de vida completo do ticket gerenciado da criação à resolução"
)
crew = Crew(
agents=[ticket_manager],
tasks=[ticket_workflow]
)
crew.kickoff()
```
### Análise e Relatórios de Suporte
```python
from crewai import Agent, Task, Crew
from crewai_tools import CrewaiEnterpriseTools
enterprise_tools = CrewaiEnterpriseTools(
enterprise_token="your_enterprise_token"
)
support_analyst = Agent(
role="Analista de Suporte",
goal="Analisar métricas de suporte e gerar insights para desempenho da equipe",
backstory="Um IA analítico que se destaca na extração de insights a partir de dados de suporte e padrões de tickets.",
tools=[enterprise_tools]
)
# Tarefa complexa envolvendo análise e geração de relatórios
analytics_task = Task(
description="""
1. Busque todos os tickets abertos nos últimos 30 dias
2. Analise tempos de resolução dos tickets e satisfação do cliente
3. Identifique problemas comuns e padrões de suporte
4. Gere relatório semanal de desempenho do suporte
""",
agent=support_analyst,
expected_output="Relatório analítico abrangente de suporte com insights de desempenho e recomendações"
)
crew = Crew(
agents=[support_analyst],
tasks=[analytics_task]
)
crew.kickoff()
```

99
docs/pt-BR/enterprise/introduction.mdx Normal file
View File

@@ -0,0 +1,99 @@
---
title: "CrewAI Enterprise"
description: "Implemente, monitore e escale seus fluxos de trabalho de agentes de IA"
icon: "globe"
---
## Introdução
CrewAI Enterprise fornece uma plataforma para implementar, monitorar e escalar seus crews e agentes em um ambiente de produção.
<Frame>
<img src="/images/enterprise/crewai-enterprise-dashboard.png" alt="CrewAI Enterprise Dashboard" />
</Frame>
CrewAI Enterprise expande o poder do framework open-source com funcionalidades projetadas para implantações em produção, colaboração e escalabilidade. Implemente seus crews em uma infraestrutura gerenciada e monitore sua execução em tempo real.
## Principais Funcionalidades
<CardGroup cols={2}>
<Card title="Implantação de Crews" icon="rocket">
Implemente seus crews em uma infraestrutura gerenciada com apenas alguns cliques
</Card>
<Card title="Acesso via API" icon="code">
Acesse seus crews implantados via REST API para integração com sistemas existentes
</Card>
<Card title="Observabilidade" icon="chart-line">
Monitore seus crews com rastreamentos de execução e logs detalhados
</Card>
<Card title="Repositório de Ferramentas" icon="toolbox">
Publique e instale ferramentas para aprimorar as capacidades de seus crews
</Card>
<Card title="Transmissão via Webhook" icon="webhook">
Transmita eventos e atualizações em tempo real para seus sistemas
</Card>
<Card title="Crew Studio" icon="paintbrush">
Crie e personalize crews utilizando uma interface no-code/low-code
</Card>
</CardGroup>
## Opções de Implantação
<CardGroup cols={3}>
<Card title="Integração com GitHub" icon="github">
Conecte-se diretamente aos seus repositórios do GitHub para implementar código
</Card>
<Card title="Crew Studio" icon="palette">
Implemente crews criados pela interface no-code do Crew Studio
</Card>
<Card title="Implantação via CLI" icon="terminal">
Use o CrewAI CLI para fluxos de trabalho de implantação mais avançados
</Card>
</CardGroup>
## Primeiros Passos
<Steps>
<Step title="Cadastre-se para uma conta">
Crie sua conta em [app.crewai.com](https://app.crewai.com)
<Card
title="Cadastre-se"
icon="user"
href="https://app.crewai.com/signup"
>
Cadastre-se
</Card>
</Step>
<Step title="Construa seu primeiro crew">
Utilize código ou o Crew Studio para construir seu crew
<Card
title="Construir Crew"
icon="paintbrush"
href="/pt-BR/enterprise/guides/build-crew"
>
Construir Crew
</Card>
</Step>
<Step title="Implemente seu crew">
Implemente seu crew na plataforma Enterprise
<Card
title="Implantar Crew"
icon="rocket"
href="/pt-BR/enterprise/guides/deploy-crew"
>
Implantar Crew
</Card>
</Step>
<Step title="Acesse seu crew">
Integre-se ao seu crew através dos endpoints de API gerados
<Card
title="Acesso via API"
icon="code"
href="/pt-BR/enterprise/guides/deploy-crew"
>
Usar a API do Crew
</Card>
</Step>
</Steps>
Para instruções detalhadas, consulte nosso [guia de implantação](/pt-BR/enterprise/guides/deploy-crew) ou clique no botão abaixo para começar.

151
docs/pt-BR/enterprise/resources/frequently-asked-questions.mdx Normal file
View File

@@ -0,0 +1,151 @@
---
title: FAQs
description: "Perguntas frequentes sobre CrewAI Enterprise"
icon: "circle-question"
---
<AccordionGroup>
<Accordion title="Como a execução de tarefas é tratada no processo hierárquico?">
No processo hierárquico, um agente gerente é criado automaticamente e coordena o fluxo de trabalho, delegando tarefas e validando resultados para uma execução eficiente e simplificada. O agente gerente utiliza ferramentas para facilitar a delegação e execução de tarefas por agentes sob sua orientação. O LLM do gerente é fundamental para o processo hierárquico e deve ser configurado corretamente para funcionar adequadamente.
</Accordion>
<Accordion title="Onde posso encontrar a documentação mais recente da CrewAI?">
A documentação mais atualizada da CrewAI está disponível em nosso site oficial de documentação: https://docs.crewai.com/
<Card href="https://docs.crewai.com/" icon="books">CrewAI Docs</Card>
</Accordion>
<Accordion title="Quais as principais diferenças entre os Processos Hierárquico e Sequencial na CrewAI?">
#### Processo Hierárquico:
- As tarefas são delegadas e executadas com base em uma cadeia de comando estruturada
- Um modelo de linguagem do gerente (`manager_llm`) deve ser especificado para o agente gerente
- O agente gerente supervisiona a execução de tarefas, planejamento, delegação e validação
- As tarefas não são pré-atribuídas; o gerente aloca tarefas para os agentes com base em suas capacidades
#### Processo Sequencial:
- As tarefas são executadas uma após a outra, garantindo uma progressão ordenada
- O resultado de uma tarefa serve como contexto para a próxima
- A execução das tarefas segue a ordem predefinida na lista de tarefas
#### Qual Processo é Melhor para Projetos Complexos?
O processo hierárquico é mais adequado para projetos complexos porque permite:
- **Alocação e delegação dinâmica de tarefas**: O agente gerente pode atribuir tarefas de acordo com as capacidades dos agentes
- **Validação e supervisão estruturadas**: O agente gerente revisa os resultados das tarefas e garante a conclusão
- **Gestão de tarefas complexas**: Controle preciso da disponibilidade de ferramentas por agente
</Accordion>
<Accordion title="Quais são os benefícios do uso de memória no framework CrewAI?">
- **Aprendizado adaptativo**: As crews tornam-se mais eficientes ao longo do tempo, adaptando-se a novas informações e aprimorando sua abordagem às tarefas
- **Personalização aprimorada**: A memória permite que os agentes recordem preferências do usuário e interações anteriores, possibilitando experiências personalizadas
- **Resolução aprimorada de problemas**: O acesso a um repositório rico em memória auxilia os agentes a tomarem decisões mais informadas, baseando-se em aprendizados anteriores e insights contextuais
</Accordion>
<Accordion title="Qual é o propósito de definir um limite máximo de RPM para um agente?">
Definir um limite máximo de RPM para um agente evita que ele faça solicitações excessivas a serviços externos, o que pode ajudar a evitar limites de taxa e melhorar o desempenho.
</Accordion>
<Accordion title="Qual o papel da entrada humana na execução de tarefas dentro de uma crew da CrewAI?">
A entrada humana permite que os agentes solicitem informações adicionais ou esclarecimentos quando necessário. Este recurso é fundamental em processos de tomada de decisão complexos ou quando os agentes precisam de mais detalhes para concluir uma tarefa com eficácia.
Para integrar a entrada humana na execução do agente, defina a flag `human_input` na definição da tarefa. Quando habilitada, o agente solicitará a entrada do usuário antes de entregar sua resposta final. Essa entrada pode fornecer contexto extra, esclarecer ambiguidades ou validar a saída do agente.
Para orientações detalhadas de implementação, veja nosso [guia Human-in-the-Loop](/pt-BR/how-to/human-in-the-loop).
</Accordion>
<Accordion title="Quais opções avançadas de customização estão disponíveis para aprimorar e personalizar o comportamento e as capacidades dos agentes na CrewAI?">
A CrewAI oferece diversas opções avançadas de customização:
- **Customização de Modelo de Linguagem**: Os agentes podem ser personalizados com modelos de linguagem específicos (`llm`) e modelos de linguagem para chamadas de função (`function_calling_llm`)
- **Configurações de Desempenho e Debug**: Ajuste o desempenho do agente e monitore suas operações
- **Modo Verbose**: Habilita registros detalhados das ações do agente, útil para depuração e otimização
- **Limite de RPM**: Define o número máximo de solicitações por minuto (`max_rpm`)
- **Máximo de Iterações**: O atributo `max_iter` permite definir o número máximo de iterações que um agente pode executar para uma única tarefa
- **Delegação e Autonomia**: Controle a capacidade do agente de delegar ou fazer perguntas com o atributo `allow_delegation` (padrão: True)
- **Integração de Entrada Humana**: Os agentes podem solicitar informações adicionais ou esclarecimentos quando necessário
</Accordion>
<Accordion title="Em quais cenários a entrada humana é particularmente útil na execução de agentes?">
A entrada humana é especialmente útil quando:
- **Os agentes precisam de informações adicionais ou esclarecimentos**: Quando se deparam com ambiguidade ou dados incompletos
- **Os agentes precisam tomar decisões complexas ou sensíveis**: A entrada humana pode auxiliar em decisões éticas ou de nuances
- **Supervisão e validação da saída do agente**: A entrada humana pode ajudar a validar resultados e prevenir erros
- **Personalização do comportamento do agente**: Entradas humanas podem fornecer feedback para aprimorar respostas dos agentes ao longo do tempo
- **Identificação e resolução de erros ou limitações**: A entrada humana auxilia a suprir lacunas de capacidade dos agentes
</Accordion>
<Accordion title="Quais são os diferentes tipos de memória disponíveis na crewAI?">
Os diferentes tipos de memória disponíveis na CrewAI são:
- **Memória de curto prazo**: Armazenamento temporário para contexto imediato
- **Memória de longo prazo**: Armazenamento persistente para padrões aprendidos e informações
- **Memória de entidade**: Armazenamento focado em entidades específicas e seus atributos
- **Memória contextual**: Memória que mantém o contexto ao longo das interações
Saiba mais sobre os diferentes tipos de memória:
<Card href="https://docs.crewai.com/concepts/memory" icon="brain">CrewAI Memory</Card>
</Accordion>
<Accordion title="Como faço para usar Output Pydantic em uma Tarefa?">
Para usar Output Pydantic em uma tarefa, você precisa definir a saída esperada da tarefa como um modelo Pydantic. Veja um exemplo rápido:
<Steps>
<Step title="Defina um modelo Pydantic">
```python
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
```
</Step>
<Step title="Crie uma tarefa com Output Pydantic">
```python
from crewai import Task, Crew, Agent
from my_models import User
task = Task(
description="Create a user with the provided name and age",
expected_output=User, # This is the Pydantic model
agent=agent,
tools=[tool1, tool2]
)
```
</Step>
<Step title="Defina o atributo output_pydantic no seu agente">
```python
from crewai import Agent
from my_models import User
agent = Agent(
role='User Creator',
goal='Create users',
backstory='I am skilled in creating user accounts',
tools=[tool1, tool2],
output_pydantic=User
)
```
</Step>
</Steps>
Aqui está um tutorial de como obter saídas estruturadas de forma consistente dos seus agentes:
<Frame>
<iframe
height="400"
width="100%"
src="https://www.youtube.com/embed/dNpKQk5uxHw"
title="YouTube video player" frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen></iframe>
</Frame>
</Accordion>
<Accordion title="Como posso criar ferramentas personalizadas para meus agentes CrewAI?">
Você pode criar ferramentas personalizadas herdando da classe `BaseTool` fornecida pela CrewAI ou usando o decorador de ferramenta. Herdar envolve definir uma nova classe que herda de `BaseTool`, especificando o nome, a descrição e o método `_run` para a lógica operacional. O decorador de ferramenta permite criar um objeto `Tool` diretamente com os atributos necessários e uma lógica funcional.
<Card href="https://docs.crewai.com/how-to/create-custom-tools" icon="code">CrewAI Tools Guide</Card>
</Accordion>
<Accordion title="Como controlar o número máximo de solicitações por minuto que toda a crew pode realizar?">
O atributo `max_rpm` define o número máximo de solicitações por minuto que a crew pode realizar para evitar limites de taxa, e irá sobrescrever as definições de `max_rpm` dos agentes individuais se você defini-lo.
</Accordion>
</AccordionGroup>

62
docs/pt-BR/examples/example.mdx Normal file
View File

@@ -0,0 +1,62 @@
---
title: Exemplos CrewAI
description: Uma coleção de exemplos que mostram como usar o framework CrewAI para automatizar fluxos de trabalho.
icon: rocket-launch
---
<CardGroup cols={3}>
<Card
title="Estratégia de Marketing"
color="#F3A78B"
href="https://github.com/crewAIInc/crewAI-examples/tree/main/marketing_strategy"
icon="bullhorn"
iconType="solid"
>
Automatize a criação de estratégias de marketing com CrewAI.
</Card>
<Card
title="Viagem Surpresa"
color="#F3A78B"
href="https://github.com/crewAIInc/crewAI-examples/tree/main/surprise_trip"
icon="plane"
iconType="duotone"
>
Crie um roteiro de viagem surpresa com CrewAI.
</Card>
<Card
title="Relacionar Perfil a Posições"
color="#F3A78B"
href="https://github.com/crewAIInc/crewAI-examples/tree/main/match_profile_to_positions"
icon="linkedin"
iconType="duotone"
>
Relacione um perfil a vagas de emprego com CrewAI.
</Card>
<Card
title="Criar Vaga"
color="#F3A78B"
href="https://github.com/crewAIInc/crewAI-examples/tree/main/job-posting"
icon="newspaper"
iconType="duotone"
>
Crie uma vaga de emprego com CrewAI.
</Card>
<Card
title="Gerador de Jogos"
color="#F3A78B"
href="https://github.com/crewAIInc/crewAI-examples/tree/main/game-builder-crew"
icon="gamepad"
iconType="duotone"
>
Crie um jogo com CrewAI.
</Card>
<Card
title="Encontrar Candidatos"
color="#F3A78B"
href="https://github.com/crewAIInc/crewAI-examples/tree/main/recruitment"
icon="user-group"
iconType="duotone"
>
Encontre candidatos a vagas com CrewAI.
</Card>
</CardGroup>

316
docs/pt-BR/guides/advanced/customizing-prompts.mdx Normal file
View File

@@ -0,0 +1,316 @@
---
title: Personalizando Prompts
description: Aprofunde-se na personalização de prompts de baixo nível no CrewAI, habilitando casos de uso super customizados e complexos para diferentes modelos e idiomas.
icon: message-pen
---
## Por Que Personalizar Prompts?
Embora os prompts padrão do CrewAI funcionem bem para muitos cenários, a personalização de baixo nível permite comportamentos de agentes significativamente mais flexíveis e poderosos. Veja por que você pode querer aproveitar esse controle mais profundo:
1. **Otimizar para LLMs específicas** – Diferentes modelos (como GPT-4, Claude ou Llama) funcionam melhor com formatos de prompt adaptados às suas arquiteturas exclusivas.
2. **Alterar o idioma** – Construa agentes que operam exclusivamente em idiomas além do inglês, lidando com nuances com precisão.
3. **Especializar para domínios complexos** – Adapte prompts para setores altamente especializados como saúde, finanças ou jurídico.
4. **Ajustar tom e estilo** – Torne os agentes mais formais, casuais, criativos ou analíticos.
5. **Suportar casos de uso super customizados** – Utilize estruturas e formatações avançadas de prompt para atender requisitos detalhados e específicos do projeto.
Este guia explora como acessar os prompts do CrewAI em um nível mais baixo, oferecendo controle granular sobre como os agentes pensam e interagem.
## Entendendo o Sistema de Prompt do CrewAI
Nos bastidores, o CrewAI adota um sistema de prompt modular que pode ser amplamente customizado:
- **Templates de agente** – Determinam o modo como cada agente aborda o papel que lhe foi atribuído.
- **Prompt slices** – Controlam comportamentos especializados como tarefas, o uso de ferramentas e a estrutura de saída.
- **Tratamento de erros** – Definem como os agentes respondem a falhas, exceções ou timeouts.
- **Prompts específicos de ferramentas** – Definem instruções detalhadas para como as ferramentas são invocadas ou utilizadas.
Confira os [templates de prompt originais no repositório do CrewAI](https://github.com/crewAIInc/crewAI/blob/main/src/crewai/translations/en.json) para ver como esses elementos são organizados. A partir daí, você pode sobrescrever ou adaptar conforme necessário para desbloquear comportamentos avançados.
## Entendendo as Instruções de Sistema Padrão
<Warning>
**Questão de Transparência em Produção**: O CrewAI injeta automaticamente instruções padrão nos seus prompts que talvez você não conheça. Esta seção explica o que acontece nos bastidores e como obter controle total.
</Warning>
Ao definir um agente com `role`, `goal` e `backstory`, o CrewAI automaticamente adiciona instruções de sistema adicionais que controlam a formatação e o comportamento. Entender essas injeções padrão é essencial para sistemas em produção onde você precisa de total transparência nos prompts.
### O Que CrewAI Injeta Automaticamente
Baseado na configuração do seu agente, o CrewAI adiciona diferentes instruções padrão:
#### Para Agentes Sem Ferramentas
```text
"I MUST use these formats, my job depends on it!"
```
#### Para Agentes Com Ferramentas
```text
"IMPORTANT: Use the following format in your response:
Thought: you should always think about what to do
Action: the action to take, only one name of [tool_names]
Action Input: the input to the action, just a simple JSON object...
```
#### Para Saídas Estruturadas (JSON/Pydantic)
```text
"Ensure your final answer contains only the content in the following format: {output_format}
Ensure the final output does not include any code block markers like ```json or ```python."
```
### Visualizando o Prompt de Sistema Completo
Para ver exatamente qual prompt está sendo enviado para seu LLM, você pode inspecionar o prompt gerado:
```python
from crewai import Agent, Crew, Task
from crewai.utilities.prompts import Prompts
# Crie seu agente
agent = Agent(
role="Data Analyst",
goal="Analyze data and provide insights",
backstory="You are an expert data analyst with 10 years of experience.",
verbose=True
)
# Crie uma tarefa de exemplo
task = Task(
description="Analyze the sales data and identify trends",
expected_output="A detailed analysis with key insights and trends",
agent=agent
)
# Crie o gerador de prompt
prompt_generator = Prompts(
agent=agent,
has_tools=len(agent.tools) > 0,
use_system_prompt=agent.use_system_prompt
)
# Gere e inspecione o prompt atual
generated_prompt = prompt_generator.task_execution()
# Imprima o prompt completo de sistema que será enviado ao LLM
if "system" in generated_prompt:
print("=== SYSTEM PROMPT ===")
print(generated_prompt["system"])
print("\n=== USER PROMPT ===")
print(generated_prompt["user"])
else:
print("=== COMPLETE PROMPT ===")
print(generated_prompt["prompt"])
# Você também pode ver como a descrição da tarefa é formatada
print("\n=== TASK CONTEXT ===")
print(f"Task Description: {task.description}")
print(f"Expected Output: {task.expected_output}")
```
### Sobrescrevendo Instruções Padrão
Você tem várias opções para obter controle total sobre os prompts:
#### Opção 1: Templates Personalizados (Recomendado)
```python
from crewai import Agent
# Defina seu próprio template de sistema sem instruções padrão
custom_system_template = """You are {role}. {backstory}
Your goal is: {goal}
Respond naturally and conversationally. Focus on providing helpful, accurate information."""
custom_prompt_template = """Task: {input}
Please complete this task thoughtfully."""
agent = Agent(
role="Research Assistant",
goal="Help users find accurate information",
backstory="You are a helpful research assistant.",
system_template=custom_system_template,
prompt_template=custom_prompt_template,
use_system_prompt=True # Use mensagens separadas system/user
)
```
#### Opção 2: Arquivo de Prompt Personalizado
Crie um arquivo `custom_prompts.json` para sobrescrever slices específicas de prompt:
```json
{
"slices": {
"no_tools": "\nProvide your best answer in a natural, conversational way.",
"tools": "\nYou have access to these tools: {tools}\n\nUse them when helpful, but respond naturally.",
"formatted_task_instructions": "Format your response as: {output_format}"
}
}
```
Em seguida, utilize no seu crew:
```python
crew = Crew(
agents=[agent],
tasks=[task],
prompt_file="custom_prompts.json",
verbose=True
)
```
#### Opção 3: Desativar Prompts de Sistema para Modelos o1
```python
agent = Agent(
role="Analyst",
goal="Analyze data",
backstory="Expert analyst",
use_system_prompt=False # Desativa separação de mensagens system prompt
)
```
### Depuração com Ferramentas de Observabilidade
Para garantir transparência em produção, integre com plataformas de observabilidade para monitorar todos os prompts e interações com LLM. Isso permite que você veja exatamente quais prompts (incluindo instruções padrão) estão sendo enviados para os seus LLMs.
Veja nossa [documentação sobre Observabilidade](/pt-BR/observability/overview) para guias detalhados de integração com diversas plataformas como Langfuse, MLflow, Weights & Biases e soluções de logging customizadas.
### Boas Práticas para Produção
1. **Sempre inspecione prompts gerados** antes de implantar em produção
2. **Use templates customizados** quando precisar de controle total sobre o conteúdo do prompt
3. **Integre ferramentas de observabilidade** para monitoramento contínuo de prompts (veja [docs de Observabilidade](/pt-BR/observability/overview))
4. **Teste com diferentes LLMs** já que instruções padrão podem se comportar de maneira diferente em cada modelo
5. **Documente suas customizações de prompt** para transparência da equipe
<Tip>
As instruções padrão existem para garantir comportamento consistente nos agentes, mas podem interferir com requisitos de domínio específicos. Use as opções de customização acima para manter controle total sobre o comportamento do seu agente em sistemas de produção.
</Tip>
## Melhores Práticas para Gerenciar Arquivos de Prompt
Ao realizar personalização de prompts em baixo nível, siga estas diretrizes para manter tudo organizado e fácil de manter:
1. **Mantenha arquivos separados** – Armazene seus prompts personalizados em arquivos JSON dedicados fora do código principal.
2. **Controle de versão** – Acompanhe as alterações no seu repositório, garantindo documentação clara das mudanças nos prompts ao longo do tempo.
3. **Organize por modelo ou idioma** – Utilize nomes como `prompts_llama.json` ou `prompts_es.json` para identificar rapidamente configurações especializadas.
4. **Documente as alterações** – Adicione comentários ou mantenha um README detalhando o propósito e o escopo das customizações.
5. **Minimize alterações** – Sobrescreva apenas os slices específicos que realmente precisam de ajuste, mantendo a funcionalidade padrão para o restante.
## O Jeito Mais Simples de Personalizar Prompts
Uma abordagem direta é criar um arquivo JSON para os prompts que deseja sobrescrever e então indicar este arquivo no seu Crew:
1. Crie um arquivo JSON com os slices de prompt atualizados.
2. Referencie este arquivo no parâmetro `prompt_file` do seu Crew.
O CrewAI então mescla suas customizações com os padrões, assim você não precisa redefinir todos os prompts. Veja como:
### Exemplo: Customização Básica de Prompt
Crie um arquivo `custom_prompts.json` com os prompts que deseja modificar. Certifique-se de listar todos os prompts de nível superior que ele deve conter, não apenas suas alterações:
```json
{
"slices": {
"format": "When responding, follow this structure:\n\nTHOUGHTS: Your step-by-step thinking\nACTION: Any tool you're using\nRESULT: Your final answer or conclusion"
}
}
```
Integre assim:
```python
from crewai import Agent, Crew, Task, Process
# Crie agentes e tarefas normalmente
researcher = Agent(
role="Research Specialist",
goal="Find information on quantum computing",
backstory="You are a quantum physics expert",
verbose=True
)
research_task = Task(
description="Research quantum computing applications",
expected_output="A summary of practical applications",
agent=researcher
)
# Crie um crew com seu arquivo de prompt personalizado
crew = Crew(
agents=[researcher],
tasks=[research_task],
prompt_file="path/to/custom_prompts.json",
verbose=True
)
# Execute o crew
result = crew.kickoff()
```
Com essas poucas edições, você conquista controle de baixo nível sobre como seus agentes se comunicam e solucionam tarefas.
## Otimizando para Modelos Específicos
Modelos diferentes respondem melhor a estruturas de prompt diferentes. Ajustes mais profundos podem aumentar significativamente o desempenho ao alinhar seus prompts às nuances de cada modelo.
### Exemplo: Template de Prompt para Llama 3.3
Por exemplo, ao lidar com o Llama 3.3 da Meta, a personalização de baixo nível pode refletir a estrutura recomendada descrita em:
https://www.llama.com/docs/model-cards-and-prompt-formats/llama3_1/#prompt-template
Veja um exemplo destacando como você pode ajustar um Agent para usar o Llama 3.3 em código:
```python
from crewai import Agent, Crew, Task, Process
from crewai_tools import DirectoryReadTool, FileReadTool
# Defina templates para mensagens de system, user (prompt) e assistant (resposta)
system_template = """<|begin_of_text|><|start_header_id|>system<|end_header_id|>{{ .System }}<|eot_id|>"""
prompt_template = """<|start_header_id|>user<|end_header_id|>{{ .Prompt }}<|eot_id|>"""
response_template = """<|start_header_id|>assistant<|end_header_id|>{{ .Response }}<|eot_id|>"""
# Crie um Agent usando layouts específicos do Llama
principal_engineer = Agent(
role="Principal Engineer",
goal="Oversee AI architecture and make high-level decisions",
backstory="You are the lead engineer responsible for critical AI systems",
verbose=True,
llm="groq/llama-3.3-70b-versatile", # Usando o modelo Llama 3
system_template=system_template,
prompt_template=prompt_template,
response_template=response_template,
tools=[DirectoryReadTool(), FileReadTool()]
)
# Defina uma tarefa de exemplo
engineering_task = Task(
description="Review AI implementation files for potential improvements",
expected_output="A summary of key findings and recommendations",
agent=principal_engineer
)
# Crie um Crew para a tarefa
llama_crew = Crew(
agents=[principal_engineer],
tasks=[engineering_task],
process=Process.sequential,
verbose=True
)
# Execute o crew
result = llama_crew.kickoff()
print(result.raw)
```
Com essa configuração, você exerce controle abrangente e de baixo nível sobre seus fluxos de trabalho baseados em Llama sem precisar de um arquivo JSON separado.
## Conclusão
A personalização de prompts em baixo nível no CrewAI abre portas para casos de uso super customizados e complexos. Mantendo arquivos de prompt organizados (ou templates inline diretos), é possível acomodar diferentes modelos, idiomas e domínios especializados. Esse nível de flexibilidade garante que você possa criar exatamente o comportamento de IA que precisa, sabendo que o CrewAI ainda fornece padrões confiáveis quando você não sobrescreve.
<Check>
Agora você tem a base para customizações avançadas de prompt no CrewAI. Seja adaptando para estruturas específicas de modelo ou restrições de domínio, esta abordagem de baixo nível permite moldar as interações dos agentes de forma altamente especializada.
</Check>

133
docs/pt-BR/guides/advanced/fingerprinting.mdx Normal file
View File

@@ -0,0 +1,133 @@
---
title: Impressão digital
description: Saiba como usar o sistema de impressão digital da CrewAI para identificar e rastrear componentes de forma única durante todo o seu ciclo de vida.
icon: fingerprint
---
## Visão geral
As impressões digitais na CrewAI fornecem uma maneira de identificar e rastrear componentes de forma única durante todo o seu ciclo de vida. Cada `Agent`, `Crew` e `Task` recebe automaticamente uma impressão digital única quando criado, que não pode ser sobrescrita manualmente.
Essas impressões digitais podem ser usadas para:
- Auditoria e rastreamento do uso de componentes
- Garantir a integridade da identidade dos componentes
- Anexar metadados aos componentes
- Criar uma cadeia rastreável de operações
## Como funciona a impressão digital
Uma impressão digital é uma instância da classe `Fingerprint` do módulo `crewai.security`. Cada impressão digital contém:
- Uma string UUID: Um identificador único para o componente, gerado automaticamente e que não pode ser definido manualmente
- Um timestamp de criação: Quando a impressão digital foi gerada, definido automaticamente e que não pode ser modificado manualmente
- Metadados: Um dicionário de informações adicionais que pode ser customizado
As impressões digitais são geradas e atribuídas automaticamente quando um componente é criado. Cada componente expõe sua impressão digital por meio de uma propriedade de somente leitura.
## Uso básico
### Acessando impressões digitais
```python
from crewai import Agent, Crew, Task
# Criar componentes - impressões digitais são geradas automaticamente
agent = Agent(
role="Data Scientist",
goal="Analyze data",
backstory="Expert in data analysis"
)
crew = Crew(
agents=[agent],
tasks=[]
)
task = Task(
description="Analyze customer data",
expected_output="Insights from data analysis",
agent=agent
)
# Acessar as impressões digitais
agent_fingerprint = agent.fingerprint
crew_fingerprint = crew.fingerprint
task_fingerprint = task.fingerprint
# Imprimir as strings UUID
print(f"Agent fingerprint: {agent_fingerprint.uuid_str}")
print(f"Crew fingerprint: {crew_fingerprint.uuid_str}")
print(f"Task fingerprint: {task_fingerprint.uuid_str}")
```
### Trabalhando com metadados das impressões digitais
Você pode adicionar metadados às impressões digitais para fornecer contexto adicional:
```python
# Adicionar metadados à impressão digital do agente
agent.security_config.fingerprint.metadata = {
"version": "1.0",
"department": "Data Science",
"project": "Customer Analysis"
}
# Acessar os metadados
print(f"Agent metadata: {agent.fingerprint.metadata}")
```
## Persistência das impressões digitais
As impressões digitais foram projetadas para persistir e permanecer inalteradas durante todo o ciclo de vida de um componente. Se você modificar um componente, a impressão digital permanece a mesma:
```python
original_fingerprint = agent.fingerprint.uuid_str
# Modificar o agente
agent.goal = "New goal for analysis"
# A impressão digital permanece inalterada
assert agent.fingerprint.uuid_str == original_fingerprint
```
## Impressões digitais determinísticas
Apesar de não ser possível definir diretamente o UUID e o timestamp de criação, é possível criar impressões digitais determinísticas usando o método `generate` com uma seed:
```python
from crewai.security import Fingerprint
# Criar uma impressão digital determinística usando uma string seed
deterministic_fingerprint = Fingerprint.generate(seed="my-agent-id")
# A mesma seed sempre gera a mesma impressão digital
same_fingerprint = Fingerprint.generate(seed="my-agent-id")
assert deterministic_fingerprint.uuid_str == same_fingerprint.uuid_str
# Também é possível definir metadados
custom_fingerprint = Fingerprint.generate(
seed="my-agent-id",
metadata={"version": "1.0"}
)
```
## Uso avançado
### Estrutura da impressão digital
Cada impressão digital possui a seguinte estrutura:
```python
from crewai.security import Fingerprint
fingerprint = agent.fingerprint
# String UUID - identificador único (gerado automaticamente)
uuid_str = fingerprint.uuid_str # e.g., "123e4567-e89b-12d3-a456-426614174000"
# Timestamp de criação (gerado automaticamente)
created_at = fingerprint.created_at # Um objeto datetime
# Metadados - informações adicionais (podem ser customizadas)
metadata = fingerprint.metadata # Um dicionário, padrão {}
```

452
docs/pt-BR/guides/agents/crafting-effective-agents.mdx Normal file
View File

@@ -0,0 +1,452 @@
---
title: Criando Agentes Eficazes
description: Aprenda as melhores práticas para projetar agentes de IA poderosos e especializados que colaboram de forma eficaz para resolver problemas complexos.
icon: robot
---
## A Arte e a Ciência do Design de Agentes
No núcleo do CrewAI está o agente – uma entidade de IA especializada projetada para desempenhar funções específicas dentro de um framework colaborativo. Embora criar agentes básicos seja simples, criar agentes verdadeiramente eficazes que geram resultados excepcionais requer a compreensão de princípios fundamentais de design e boas práticas.
Este guia vai ajudá-lo a dominar a arte de projetar agentes, permitindo criar personas de IA especializadas que colaboram de forma eficaz, pensam criticamente e produzem resultados de alta qualidade adaptados às suas necessidades específicas.
### Por Que o Design de Agentes é Importante
A forma como você define seus agentes impacta significativamente:
1. **Qualidade do resultado**: Agentes bem projetados produzem resultados mais relevantes e de alta qualidade
2. **Eficiência da colaboração**: Agentes com habilidades complementares trabalham juntos de maneira mais eficiente
3. **Desempenho nas tarefas**: Agentes com papéis e objetivos claros executam tarefas de forma mais eficaz
4. **Escalabilidade do sistema**: Agentes bem projetados podem ser reutilizados em múltiplos crews e contextos
Vamos explorar as melhores práticas para criar agentes que se destacam nessas dimensões.
## A Regra 80/20: Foque Mais nas Tarefas do que nos Agentes
Ao construir sistemas de IA eficazes, lembre-se deste princípio crucial: **80% do seu esforço deve ser dedicado ao design das tarefas, e apenas 20% à definição dos agentes**.
Por quê? Porque mesmo o agente mais perfeitamente definido irá falhar com tarefas mal elaboradas, mas tarefas bem projetadas podem elevar até mesmo agentes simples. Isso significa:
- Dedique a maior parte do seu tempo escrevendo instruções claras para as tarefas
- Defina entradas detalhadas e saídas esperadas
- Adicione exemplos e contexto para orientar a execução
- Reserve o tempo restante para o papel, objetivo e histórico do agente
Isso não quer dizer que o design do agente não seja importante – ele é, sim. Mas o design das tarefas é onde ocorrem a maioria das falhas de execução, então priorize de acordo.
## Princípios Fundamentais do Design de Agentes Eficazes
### 1. O Framework Papel–Objetivo–Histórico
Os agentes mais poderosos no CrewAI têm uma base sólida em três elementos-chave:
#### Papel: A Função Especializada do Agente
O papel define o que o agente faz e sua área de especialização. Ao criar papéis:
- **Seja específico e especializado**: Em vez de “Escritor”, use “Especialista em Documentação Técnica” ou “Contador de Histórias Criativo”
- **Alinhe com profissões do mundo real**: Baseie os papéis em arquétipos profissionais reconhecíveis
- **Inclua expertise no domínio**: Especifique o campo de conhecimento do agente (ex: “Analista Financeiro especializado em tendências de mercado”)
**Exemplos de papéis eficazes:**
```yaml
role: "Pesquisador Sênior de UX especializado em análise de entrevistas com usuários"
role: "Arquiteto de Software Full-Stack com expertise em sistemas distribuídos"
role: "Diretor de Comunicação Corporativa especializado em gestão de crises"
```
#### Objetivo: A Finalidade e Motivação do Agente
O objetivo direciona os esforços do agente e orienta seu processo de tomada de decisão. Objetivos eficazes devem:
- **Ser claros e focados em resultado**: Defina o que o agente precisa alcançar
- **Enfatizar padrões de qualidade**: Inclua expectativas sobre a qualidade do trabalho
- **Incorporar critérios de sucesso**: Ajude o agente a entender o que é considerado “bom”
**Exemplos de objetivos eficazes:**
```yaml
goal: "Descobrir insights acionáveis analisando dados de entrevistas, identificando padrões recorrentes, necessidades não atendidas e oportunidades de melhoria"
goal: "Projetar arquiteturas de sistemas robustas e escaláveis que equilibrem performance, manutenção e custo-benefício"
goal: "Criar comunicações de crise claras e empáticas, abordando as preocupações das partes interessadas e protegendo a reputação organizacional"
```
#### Histórico: Experiência e Perspectiva do Agente
O histórico aprofunda o agente, influenciando como ele aborda problemas e interage com os demais. Bons históricos:
- **Estabelecem expertise e experiência**: Explique como o agente adquiriu suas habilidades
- **Definem estilo de trabalho e valores**: Descreva como o agente encara seu trabalho
- **Criam uma persona coesa**: Garanta que todos os elementos do histórico estejam alinhados ao papel e ao objetivo
**Exemplos de históricos eficazes:**
```yaml
backstory: "Você passou 15 anos conduzindo e analisando pesquisas com usuários em grandes empresas de tecnologia. Tem talento para ler nas entrelinhas e identificar padrões que outros não enxergam. Acredita que uma boa experiência do usuário é invisível e que os melhores insights vêm tanto do que os usuários não dizem quanto do que dizem."
backstory: "Com mais de 20 anos de experiência construindo sistemas distribuídos em larga escala, você desenvolveu uma abordagem pragmática para arquitetura de software. Viu sistemas bem sucedidos e fracassados e aprendeu lições valiosas com ambos. Equilibra as melhores práticas teóricas com restrições práticas e sempre considera os aspectos de manutenção e operação em seus projetos."
backstory: "Como um profissional de comunicação experiente que já orientou múltiplas organizações em crises de grande repercussão, você entende a importância da transparência, agilidade e empatia em respostas a crises. Tem uma abordagem metódica para criar mensagens que abordam preocupações mantendo a credibilidade da organização."
```
### 2. Especialistas em vez de Generalistas
Agentes desempenham muito melhor quando recebem papéis especializados em vez de papéis genéricos. Um agente altamente focado gera resultados mais precisos e relevantes:
**Genérico (Menos Eficaz):**
```yaml
role: "Writer"
```
**Especializado (Mais Eficaz):**
```yaml
role: "Redator Técnico de Blog especializado em explicar conceitos complexos de IA para públicos não técnicos"
```
**Vantagens dos Especialistas:**
- Compreensão mais clara do resultado esperado
- Performance mais consistente
- Melhor alinhamento com tarefas específicas
- Maior capacidade de fazer julgamentos específicos do domínio
### 3. Equilibrando Especialização e Versatilidade
Agentes eficazes equilibram bem a especialização (fazer uma coisa muito bem) e a versatilidade (adaptar-se a diversas situações):
- **Especialize no papel, seja versátil na aplicação**: Crie agentes com habilidades especializadas aplicáveis em múltiplos contextos
- **Evite definições excessivamente restritas**: Garanta que agentes possam lidar com variações dentro de sua área de expertise
- **Considere o contexto colaborativo**: Projete agentes cujas especialidades complementem os demais do crew
### 4. Definição Nível Apropriado de Expertise
O nível de expertise atribuído ao agente determina como ele realiza as tarefas:
- **Agentes iniciantes**: Bons para tarefas simples, brainstorm, rascunhos iniciais
- **Agentes intermediários**: Adequados para a maioria das tarefas padrão com execução confiável
- **Agentes especialistas**: Ideais para tarefas complexas e especializadas que exigem profundidade e nuances
- **Agentes de classe mundial**: Reservados para tarefas críticas onde a qualidade excepcional é essencial
Escolha o nível de expertise baseado na complexidade da tarefa e no padrão de qualidade exigido. Em crews colaborativos, tendem a funcionar melhor equipes com níveis variados de expertise, reservando maior especialização para as funções mais chave.
## Exemplos Práticos: Antes e Depois
Veja exemplos de definições de agentes antes e depois de aplicar essas boas práticas:
### Exemplo 1: Agente de Criação de Conteúdo
**Antes:**
```yaml
role: "Writer"
goal: "Write good content"
backstory: "You are a writer who creates content for websites."
```
**Depois:**
```yaml
role: "Estrategista de Conteúdo B2B para Tecnologia"
goal: "Criar conteúdos envolventes e tecnicamente precisos, explicando tópicos complexos em linguagem acessível, promovendo engajamento e apoiando os objetivos do negócio"
backstory: "Você passou uma década criando conteúdos para empresas líderes em tecnologia, especializando-se na tradução de conceitos técnicos para públicos empresariais. É ótimo em pesquisa, entrevistas com especialistas e estruturação da informação para máxima clareza e impacto. Acredita que o melhor conteúdo B2B educa antes de vender, construindo confiança através da expertise genuína e não do hype de marketing."
```
### Exemplo 2: Agente de Pesquisa
**Antes:**
```yaml
role: "Researcher"
goal: "Find information"
backstory: "You are good at finding information online."
```
**Depois:**
```yaml
role: "Especialista em Pesquisa Acadêmica de Tecnologias Emergentes"
goal: "Descobrir e sintetizar pesquisas de ponta, identificando tendências, metodologias e resultados principais, avaliando a qualidade e confiabilidade das fontes"
backstory: "Com formação em ciência da computação e biblioteconomia, você dominou a arte da pesquisa digital. Já trabalhou com equipes de pesquisa em universidades de prestígio e sabe como navegar bancos de dados acadêmicos, avaliar a qualidade das pesquisas e sintetizar descobertas em diferentes áreas. Seu método é rigoroso: sempre cruza informações e rastreia a origem dos dados antes de chegar a conclusões."
```
## Criando Tarefas Eficazes para seus Agentes
Embora o design dos agentes seja importante, o design das tarefas é crítico para uma boa execução. Aqui estão as melhores práticas para definir tarefas que irão impulsionar o sucesso dos seus agentes:
### A Anatomia de uma Tarefa Eficaz
Uma tarefa bem projetada tem dois componentes-chave com propósitos distintos:
#### Descrição da Tarefa: O Processo
A descrição deve focar no que fazer e como fazer, incluindo:
- Instruções detalhadas de execução
- Contexto e informações de fundo
- Escopo e restrições
- Passos do processo a serem seguidos
#### Saída Esperada: O Entregável
A saída esperada deve definir como o resultado final deve ser apresentado:
- Especificações de formato (markdown, JSON, etc.)
- Estrutura exigida
- Critérios de qualidade
- Exemplos de bons entregáveis (sempre que possível)
### Melhores Práticas para Design de Tarefas
#### 1. Propósito Único, Saída Única
Tarefas funcionam melhor quando são focadas em um objetivo claro:
**Exemplo Ruim (Muito Abrangente):**
```yaml
task_description: "Research market trends, analyze the data, and create a visualization."
```
**Exemplo Bom (Focado):**
```yaml
# Task 1
research_task:
description: "Research the top 5 market trends in the AI industry for 2024."
expected_output: "A markdown list of the 5 trends with supporting evidence."
# Task 2
analysis_task:
description: "Analyze the identified trends to determine potential business impacts."
expected_output: "A structured analysis with impact ratings (High/Medium/Low)."
# Task 3
visualization_task:
description: "Create a visual representation of the analyzed trends."
expected_output: "A description of a chart showing trends and their impact ratings."
```
#### 2. Seja Explícito Sobre Entradas e Saídas
Sempre especifique claramente quais são as entradas da tarefa e como deve ser o resultado:
**Exemplo:**
```yaml
analysis_task:
description: >
Analyze the customer feedback data from the CSV file.
Focus on identifying recurring themes related to product usability.
Consider sentiment and frequency when determining importance.
expected_output: >
A markdown report with the following sections:
1. Executive summary (3-5 bullet points)
2. Top 3 usability issues with supporting data
3. Recommendations for improvement
```
#### 3. Inclua Propósito e Contexto
Explique por que a tarefa importa e como ela se encaixa no fluxo de trabalho maior:
**Exemplo:**
```yaml
competitor_analysis_task:
description: >
Analyze our three main competitors' pricing strategies.
This analysis will inform our upcoming pricing model revision.
Focus on identifying patterns in how they price premium features
and how they structure their tiered offerings.
```
#### 4. Use Ferramentas de Saída Estruturada
Para saídas legíveis por máquina, especifique claramente o formato:
**Exemplo:**
```yaml
data_extraction_task:
description: "Extract key metrics from the quarterly report."
expected_output: "JSON object with the following keys: revenue, growth_rate, customer_acquisition_cost, and retention_rate."
```
## Erros Comuns a Evitar
Baseando-se em experiências de casos reais, estes são os erros mais comuns no design de agentes e tarefas:
### 1. Instruções de Tarefa Pouco Claras
**Problema:** Tarefas sem detalhes suficientes, dificultando a execução pelo agente.
**Exemplo de Design Ruim:**
```yaml
research_task:
description: "Research AI trends."
expected_output: "A report on AI trends."
```
**Versão Melhorada:**
```yaml
research_task:
description: >
Research the top emerging AI trends for 2024 with a focus on:
1. Enterprise adoption patterns
2. Technical breakthroughs in the past 6 months
3. Regulatory developments affecting implementation
For each trend, identify key companies, technologies, and potential business impacts.
expected_output: >
A comprehensive markdown report with:
- Executive summary (5 bullet points)
- 5-7 major trends with supporting evidence
- For each trend: definition, examples, and business implications
- References to authoritative sources
```
### 2. "Tarefas-Deus" Que Tentam Fazer Demais
**Problema:** Tarefas que combinam múltiplas operações complexas em um único conjunto de instruções.
**Exemplo de Design Ruim:**
```yaml
comprehensive_task:
description: "Research market trends, analyze competitor strategies, create a marketing plan, and design a launch timeline."
```
**Versão Melhorada:**
Divida em tarefas sequenciais e focadas:
```yaml
# Task 1: Research
market_research_task:
description: "Research current market trends in the SaaS project management space."
expected_output: "A markdown summary of key market trends."
# Task 2: Competitive Analysis
competitor_analysis_task:
description: "Analyze strategies of the top 3 competitors based on the market research."
expected_output: "A comparison table of competitor strategies."
context: [market_research_task]
# Continue with additional focused tasks...
```
### 3. Descrição e Saída Esperada Desalinhadas
**Problema:** O que a descrição pede não corresponde ao que a saída esperada especifica.
**Exemplo de Design Ruim:**
```yaml
analysis_task:
description: "Analyze customer feedback to find areas of improvement."
expected_output: "A marketing plan for the next quarter."
```
**Versão Melhorada:**
```yaml
analysis_task:
description: "Analyze customer feedback to identify the top 3 areas for product improvement."
expected_output: "A report listing the 3 priority improvement areas with supporting customer quotes and data points."
```
### 4. Não Entender o Processo Você Mesmo
**Problema:** Pedir para o agente executar tarefas que você mesmo não entende completamente.
**Solução:**
1. Tente realizar a tarefa manualmente primeiro
2. Documente o processo, pontos de decisão e fontes de informação
3. Use esta documentação como base para a descrição da tarefa
### 5. Uso Prematuro de Estruturas Hierárquicas
**Problema:** Criar hierarquias de agentes desnecessariamente complexas quando processos sequenciais seriam suficientes.
**Solução:** Comece com processos sequenciais e só adote modelos hierárquicos quando a complexidade do fluxo de trabalho realmente justificar.
### 6. Definições Genéricas ou Pouco Claras de Agentes
**Problema:** Definições genéricas de agentes levam a resultados genéricos.
**Exemplo de Design Ruim:**
```yaml
agent:
role: "Business Analyst"
goal: "Analyze business data"
backstory: "You are good at business analysis."
```
**Versão Melhorada:**
```yaml
agent:
role: "Especialista em Métricas SaaS focado em startups em fase de crescimento"
goal: "Identificar insights acionáveis em dados de negócios que possam impactar diretamente a retenção de clientes e o crescimento de receita"
backstory: "Com mais de 10 anos analisando modelos de negócios SaaS, você desenvolveu um olhar apurado para as métricas que realmente impulsionam crescimento sustentável. Já ajudou diversas empresas a identificar pontos de alavancagem que mudaram o rumo dos negócios. Acredita em conectar dados a recomendações específicas e acionáveis, e não apenas a observações genéricas."
```
## Estratégias Avançadas de Design de Agentes
### Projetando para Colaboração
Ao criar agentes que trabalharão em conjunto em um crew, pense em:
- **Habilidades complementares**: Projete agentes com competências distintas, porém complementares
- **Pontos de transferência**: Defina interfaces claras para a passagem de trabalho entre agentes
- **Tensão construtiva**: Às vezes, agentes com perspectivas um pouco diferentes promovem melhores resultados por meio de diálogos construtivos
Por exemplo, um crew de criação de conteúdo pode incluir:
```yaml
# Research Agent
role: "Research Specialist for technical topics"
goal: "Gather comprehensive, accurate information from authoritative sources"
backstory: "You are a meticulous researcher with a background in library science..."
# Writer Agent
role: "Technical Content Writer"
goal: "Transform research into engaging, clear content that educates and informs"
backstory: "You are an experienced writer who excels at explaining complex concepts..."
# Editor Agent
role: "Content Quality Editor"
goal: "Ensure content is accurate, well-structured, and polished while maintaining consistency"
backstory: "With years of experience in publishing, you have a keen eye for detail..."
```
### Criando Usuários Especializados de Ferramentas
Alguns agentes podem ser projetados para explorar certas ferramentas de maneira eficiente:
```yaml
role: "Data Analysis Specialist"
goal: "Derive meaningful insights from complex datasets through statistical analysis"
backstory: "With a background in data science, you excel at working with structured and unstructured data..."
tools: [PythonREPLTool, DataVisualizationTool, CSVAnalysisTool]
```
### Personalizando Agentes para Capacidades do LLM
Diferentes LLMs têm pontos fortes distintos. Projete seus agentes levando essas capacidades em conta:
```yaml
# For complex reasoning tasks
analyst:
role: "Data Insights Analyst"
goal: "..."
backstory: "..."
llm: openai/gpt-4o
# For creative content
writer:
role: "Creative Content Writer"
goal: "..."
backstory: "..."
llm: anthropic/claude-3-opus
```
## Testando e Iterando no Design de Agentes
A construção de agentes geralmente é um processo iterativo. Veja como colocar em prática:
1. **Comece com um protótipo**: Crie uma definição inicial do agente
2. **Teste com tarefas de exemplo**: Avalie o desempenho em tarefas representativas
3. **Analise os resultados**: Identifique pontos fortes e fracos
4. **Refine a definição**: Ajuste papel, objetivo e histórico conforme suas observações
5. **Teste em colaboração**: Avalie como o agente se sai em conjunto no crew
## Conclusão
Criar agentes eficazes é tanto arte quanto ciência. Ao definir cuidadosamente papéis, objetivos e históricos alinhados às suas necessidades, e combinar isso com tarefas bem projetadas, você constrói colaboradores de IA especializados capazes de gerar resultados excepcionais.
Lembre-se de que o design de agentes e tarefas é um processo iterativo. Comece com essas boas práticas, observe os agentes em ação e refine sua abordagem conforme necessário. E sempre tenha em mente a regra 80/20 – concentre a maior parte do esforço em criar tarefas claras e focadas para tirar o melhor de seus agentes.
<Check>
Parabéns! Agora você entende os princípios e práticas do design eficaz de agentes. Aplique estas técnicas para criar agentes poderosos e especializados que trabalham juntos perfeitamente e realizam tarefas complexas.
</Check>
## Próximos Passos
- Experimente diferentes configurações de agentes para o seu caso de uso
- Aprenda sobre [como construir seu primeiro crew](/pt-BR/guides/crews/first-crew) para ver como agentes trabalham juntos
- Explore os [CrewAI Flows](/pt-BR/guides/flows/first-flow) para uma orquestração mais avançada

503
docs/pt-BR/guides/concepts/evaluating-use-cases.mdx Normal file
View File

@@ -0,0 +1,503 @@
---
title: Avaliando Casos de Uso para CrewAI
description: Aprenda a avaliar as necessidades da sua aplicação de IA e escolher a abordagem certa entre Crews e Flows com base nos requisitos de complexidade e precisão.
icon: scale-balanced
---
## Entendendo o Framework de Decisão
Ao construir aplicações de IA com CrewAI, uma das decisões mais importantes que você tomará é escolher a abordagem correta para o seu caso de uso específico. Você deve usar uma Crew? Um Flow? Uma combinação dos dois? Este guia vai ajudar você a avaliar seus requisitos e tomar decisões arquitetônicas embasadas.
No centro dessa decisão está o entendimento da relação entre **complexidade** e **precisão** em sua aplicação:
<Frame caption="Matriz de Complexidade vs. Precisão para Aplicações CrewAI">
<img src="/images/complexity_precision.png" alt="Matriz de Complexidade vs. Precisão" />
</Frame>
Essa matriz ajuda a visualizar como diferentes abordagens se alinham com os requisitos variados de complexidade e precisão. Vamos explorar o significado de cada quadrante e como isso orienta suas escolhas arquiteturais.
## Explicando a Matriz Complexidade-Precisão
### O que é Complexidade?
No contexto das aplicações CrewAI, **complexidade** refere-se a:
- O número de etapas ou operações distintas necessárias
- A diversidade de tarefas que precisam ser realizadas
- As interdependências entre diferentes componentes
- A necessidade de lógica condicional e ramificações
- A sofisticação do fluxo de trabalho como um todo
### O que é Precisão?
**Precisão** nesse contexto refere-se a:
- O grau de exatidão exigido no resultado final
- A necessidade de resultados estruturados e previsíveis
- A importância da reprodutibilidade
- O nível de controle necessário sobre cada etapa
- A tolerância à variação nos resultados
### Os Quatro Quadrantes
#### 1. Baixa Complexidade, Baixa Precisão
**Características:**
- Tarefas simples e diretas
- Tolerância a alguma variação nos resultados
- Número limitado de etapas
- Aplicações criativas ou exploratórias
**Abordagem Recomendada:** Crews simples com poucos agentes
**Exemplos de Casos de Uso:**
- Geração básica de conteúdo
- Brainstorming de ideias
- Tarefas simples de sumarização
- Assistência à escrita criativa
#### 2. Baixa Complexidade, Alta Precisão
**Características:**
- Fluxos de trabalho simples que exigem resultados exatos e estruturados
- Necessidade de resultados reproduzíveis
- Poucas etapas, mas alto requisito de precisão
- Frequentemente envolve processamento ou transformação de dados
**Abordagem Recomendada:** Flows com chamadas diretas a LLM ou Crews simples com saídas estruturadas
**Exemplos de Casos de Uso:**
- Extração e transformação de dados
- Preenchimento e validação de formulários
- Geração estruturada de conteúdo (JSON, XML)
- Tarefas simples de classificação
#### 3. Alta Complexidade, Baixa Precisão
**Características:**
- Processos multiestágio com muitas etapas
- Saídas criativas ou exploratórias
- Interações complexas entre componentes
- Tolerância à variação nos resultados finais
**Abordagem Recomendada:** Crews complexas com múltiplos agentes especializados
**Exemplos de Casos de Uso:**
- Pesquisa e análise
- Pipelines de criação de conteúdo
- Análise exploratória de dados
- Solução criativa de problemas
#### 4. Alta Complexidade, Alta Precisão
**Características:**
- Fluxos de trabalho complexos que requerem saídas estruturadas
- Múltiplas etapas interdependentes com rígida exigência de precisão
- Necessidade tanto de processamento sofisticado quanto de resultados precisos
- Frequentemente aplicações críticas
**Abordagem Recomendada:** Flows orquestrando múltiplas Crews com etapas de validação
**Exemplos de Casos de Uso:**
- Sistemas corporativos de suporte à decisão
- Pipelines complexos de processamento de dados
- Processamento de documentos em múltiplos estágios
- Aplicações em indústrias reguladas
## Escolhendo Entre Crews e Flows
### Quando Escolher Crews
Crews são ideais quando:
1. **Você precisa de inteligência colaborativa** - Múltiplos agentes com especializações diferentes precisam trabalhar juntos
2. **O problema requer pensamento emergente** - A solução se beneficia de diferentes perspectivas e abordagens
3. **A tarefa é principalmente criativa ou analítica** - O trabalho envolve pesquisa, criação de conteúdo ou análise
4. **Você valoriza adaptabilidade mais do que estrutura rígida** - O fluxo de trabalho pode se beneficiar da autonomia dos agentes
5. **O formato da saída pode ser um pouco flexível** - Alguma variação na estrutura do resultado é aceitável
```python
# Example: Research Crew for market analysis
from crewai import Agent, Crew, Process, Task
# Create specialized agents
researcher = Agent(
role="Market Research Specialist",
goal="Find comprehensive market data on emerging technologies",
backstory="You are an expert at discovering market trends and gathering data."
)
analyst = Agent(
role="Market Analyst",
goal="Analyze market data and identify key opportunities",
backstory="You excel at interpreting market data and spotting valuable insights."
)
# Define their tasks
research_task = Task(
description="Research the current market landscape for AI-powered healthcare solutions",
expected_output="Comprehensive market data including key players, market size, and growth trends",
agent=researcher
)
analysis_task = Task(
description="Analyze the market data and identify the top 3 investment opportunities",
expected_output="Analysis report with 3 recommended investment opportunities and rationale",
agent=analyst,
context=[research_task]
)
# Create the crew
market_analysis_crew = Crew(
agents=[researcher, analyst],
tasks=[research_task, analysis_task],
process=Process.sequential,
verbose=True
)
# Run the crew
result = market_analysis_crew.kickoff()
```
### Quando Escolher Flows
Flows são ideais quando:
1. **Você precisa de controle preciso da execução** - O fluxo de trabalho exige sequenciamento exato e gerenciamento de estado
2. **A aplicação tem requisitos complexos de estado** - Você precisa manter e transformar estado ao longo de múltiplas etapas
3. **Você precisa de saídas estruturadas e previsíveis** - A aplicação exige resultados consistentes e formatados
4. **O fluxo de trabalho envolve lógica condicional** - Caminhos diferentes precisam ser seguidos com base em resultados intermediários
5. **Você precisa combinar IA com código procedural** - A solução demanda tanto capacidades de IA quanto programação tradicional
```python
# Example: Customer Support Flow with structured processing
from crewai.flow.flow import Flow, listen, router, start
from pydantic import BaseModel
from typing import List, Dict
# Define structured state
class SupportTicketState(BaseModel):
ticket_id: str = ""
customer_name: str = ""
issue_description: str = ""
category: str = ""
priority: str = "medium"
resolution: str = ""
satisfaction_score: int = 0
class CustomerSupportFlow(Flow[SupportTicketState]):
@start()
def receive_ticket(self):
# In a real app, this might come from an API
self.state.ticket_id = "TKT-12345"
self.state.customer_name = "Alex Johnson"
self.state.issue_description = "Unable to access premium features after payment"
return "Ticket received"
@listen(receive_ticket)
def categorize_ticket(self, _):
# Use a direct LLM call for categorization
from crewai import LLM
llm = LLM(model="openai/gpt-4o-mini")
prompt = f"""
Categorize the following customer support issue into one of these categories:
- Billing
- Account Access
- Technical Issue
- Feature Request
- Other
Issue: {self.state.issue_description}
Return only the category name.
"""
self.state.category = llm.call(prompt).strip()
return self.state.category
@router(categorize_ticket)
def route_by_category(self, category):
# Route to different handlers based on category
return category.lower().replace(" ", "_")
@listen("billing")
def handle_billing_issue(self):
# Handle billing-specific logic
self.state.priority = "high"
# More billing-specific processing...
return "Billing issue handled"
@listen("account_access")
def handle_access_issue(self):
# Handle access-specific logic
self.state.priority = "high"
# More access-specific processing...
return "Access issue handled"
# Additional category handlers...
@listen("billing", "account_access", "technical_issue", "feature_request", "other")
def resolve_ticket(self, resolution_info):
# Final resolution step
self.state.resolution = f"Issue resolved: {resolution_info}"
return self.state.resolution
# Run the flow
support_flow = CustomerSupportFlow()
result = support_flow.kickoff()
```
### Quando Combinar Crews e Flows
As aplicações mais sofisticadas frequentemente se beneficiam da combinação de Crews e Flows:
1. **Processos complexos em múltiplos estágios** - Use Flows para orquestrar o processo geral e Crews para sub-tarefas complexas
2. **Aplicações que exigem criatividade e estrutura** - Use Crews para tarefas criativas e Flows para processamento estruturado
3. **Aplicações corporativas de IA** - Use Flows para gerenciar estado e fluxo de processo enquanto aproveita Crews para tarefas especializadas
```python
# Example: Content Production Pipeline combining Crews and Flows
from crewai.flow.flow import Flow, listen, start
from crewai import Agent, Crew, Process, Task
from pydantic import BaseModel
from typing import List, Dict
class ContentState(BaseModel):
topic: str = ""
target_audience: str = ""
content_type: str = ""
outline: Dict = {}
draft_content: str = ""
final_content: str = ""
seo_score: int = 0
class ContentProductionFlow(Flow[ContentState]):
@start()
def initialize_project(self):
# Set initial parameters
self.state.topic = "Sustainable Investing"
self.state.target_audience = "Millennial Investors"
self.state.content_type = "Blog Post"
return "Project initialized"
@listen(initialize_project)
def create_outline(self, _):
# Use a research crew to create an outline
researcher = Agent(
role="Content Researcher",
goal=f"Research {self.state.topic} for {self.state.target_audience}",
backstory="You are an expert researcher with deep knowledge of content creation."
)
outliner = Agent(
role="Content Strategist",
goal=f"Create an engaging outline for a {self.state.content_type}",
backstory="You excel at structuring content for maximum engagement."
)
research_task = Task(
description=f"Research {self.state.topic} focusing on what would interest {self.state.target_audience}",
expected_output="Comprehensive research notes with key points and statistics",
agent=researcher
)
outline_task = Task(
description=f"Create an outline for a {self.state.content_type} about {self.state.topic}",
expected_output="Detailed content outline with sections and key points",
agent=outliner,
context=[research_task]
)
outline_crew = Crew(
agents=[researcher, outliner],
tasks=[research_task, outline_task],
process=Process.sequential,
verbose=True
)
# Run the crew and store the result
result = outline_crew.kickoff()
# Parse the outline (in a real app, you might use a more robust parsing approach)
import json
try:
self.state.outline = json.loads(result.raw)
except:
# Fallback if not valid JSON
self.state.outline = {"sections": result.raw}
return "Outline created"
@listen(create_outline)
def write_content(self, _):
# Use a writing crew to create the content
writer = Agent(
role="Content Writer",
goal=f"Write engaging content for {self.state.target_audience}",
backstory="You are a skilled writer who creates compelling content."
)
editor = Agent(
role="Content Editor",
goal="Ensure content is polished, accurate, and engaging",
backstory="You have a keen eye for detail and a talent for improving content."
)
writing_task = Task(
description=f"Write a {self.state.content_type} about {self.state.topic} following this outline: {self.state.outline}",
expected_output="Complete draft content in markdown format",
agent=writer
)
editing_task = Task(
description="Edit and improve the draft content for clarity, engagement, and accuracy",
expected_output="Polished final content in markdown format",
agent=editor,
context=[writing_task]
)
writing_crew = Crew(
agents=[writer, editor],
tasks=[writing_task, editing_task],
process=Process.sequential,
verbose=True
)
# Run the crew and store the result
result = writing_crew.kickoff()
self.state.final_content = result.raw
return "Content created"
@listen(write_content)
def optimize_for_seo(self, _):
# Use a direct LLM call for SEO optimization
from crewai import LLM
llm = LLM(model="openai/gpt-4o-mini")
prompt = f"""
Analyze this content for SEO effectiveness for the keyword "{self.state.topic}".
Rate it on a scale of 1-100 and provide 3 specific recommendations for improvement.
Content: {self.state.final_content[:1000]}... (truncated for brevity)
Format your response as JSON with the following structure:
{{
"score": 85,
"recommendations": [
"Recommendation 1",
"Recommendation 2",
"Recommendation 3"
]
}}
"""
seo_analysis = llm.call(prompt)
# Parse the SEO analysis
import json
try:
analysis = json.loads(seo_analysis)
self.state.seo_score = analysis.get("score", 0)
return analysis
except:
self.state.seo_score = 50
return {"score": 50, "recommendations": ["Unable to parse SEO analysis"]}
# Run the flow
content_flow = ContentProductionFlow()
result = content_flow.kickoff()
```
## Framework Prático de Avaliação
Para determinar a abordagem certa para seu caso de uso específico, siga este framework passo a passo:
### Passo 1: Avalie a Complexidade
Classifique a complexidade do seu aplicativo numa escala de 1-10 considerando:
1. **Número de etapas**: Quantas operações distintas são necessárias?
- 1-3 etapas: Baixa complexidade (1-3)
- 4-7 etapas: Média complexidade (4-7)
- 8+ etapas: Alta complexidade (8-10)
2. **Interdependências**: Quão interligadas estão as partes diferentes?
- Poucas dependências: Baixa complexidade (1-3)
- Algumas dependências: Média complexidade (4-7)
- Muitas dependências complexas: Alta complexidade (8-10)
3. **Lógica condicional**: Quanto de ramificação e tomada de decisão é necessário?
- Processo linear: Baixa complexidade (1-3)
- Alguma ramificação: Média complexidade (4-7)
- Árvores de decisão complexas: Alta complexidade (8-10)
4. **Conhecimento de domínio**: Quão especializado deve ser o conhecimento requerido?
- Conhecimento geral: Baixa complexidade (1-3)
- Algum conhecimento especializado: Média complexidade (4-7)
- Grande especialização em múltiplos domínios: Alta complexidade (8-10)
Calcule a média das pontuações para determinar sua complexidade geral.
### Passo 2: Avalie os Requisitos de Precisão
Classifique seus requisitos de precisão numa escala de 1-10 considerando:
1. **Estrutura da saída**: Quão estruturado o resultado deve ser?
- Texto livre: Baixa precisão (1-3)
- Semi-estruturado: Média precisão (4-7)
- Estritamente formatado (JSON, XML): Alta precisão (8-10)
2. **Necessidade de exatidão**: Qual a importância da precisão factual?
- Conteúdo criativo: Baixa precisão (1-3)
- Conteúdo informacional: Média precisão (4-7)
- Informação crítica: Alta precisão (8-10)
3. **Reprodutibilidade**: Quão consistentes devem ser os resultados entre execuções?
- Variação aceitável: Baixa precisão (1-3)
- Alguma consistência necessária: Média precisão (4-7)
- Exata reprodutibilidade: Alta precisão (8-10)
4. **Tolerância a erros**: Qual o impacto de erros?
- Baixo impacto: Baixa precisão (1-3)
- Impacto moderado: Média precisão (4-7)
- Alto impacto: Alta precisão (8-10)
Calcule a média das pontuações para determinar seu requisito geral de precisão.
### Passo 3: Mapeie na Matriz
Plote as pontuações de complexidade e precisão na matriz:
- **Baixa Complexidade (1-4), Baixa Precisão (1-4)**: Crews simples
- **Baixa Complexidade (1-4), Alta Precisão (5-10)**: Flows com chamadas diretas a LLM
- **Alta Complexidade (5-10), Baixa Precisão (1-4)**: Crews complexas
- **Alta Complexidade (5-10), Alta Precisão (5-10)**: Flows orquestrando Crews
### Passo 4: Considere Fatores Adicionais
Além de complexidade e precisão, considere:
1. **Tempo de desenvolvimento**: Crews costumam ser mais rápidas para prototipar
2. **Necessidades de manutenção**: Flows proporcionam melhor manutenção a longo prazo
3. **Expertise do time**: Considere a familiaridade de sua equipe com as abordagens
4. **Requisitos de escalabilidade**: Flows normalmente escalam melhor para aplicações complexas
5. **Necessidades de integração**: Considere como a solução se integrará aos sistemas existentes
## Conclusão
Escolher entre Crews e Flows — ou combiná-los — é uma decisão arquitetônica crítica que impacta a efetividade, manutenibilidade e escalabilidade da sua aplicação CrewAI. Ao avaliar seu caso de uso nas dimensões de complexidade e precisão, você toma decisões inteligentes que alinham-se aos seus requisitos.
Lembre-se de que a melhor abordagem geralmente evolui na medida em que sua aplicação amadurece. Comece com a solução mais simples que atenda às suas necessidades e esteja preparado para refinar sua arquitetura conforme for ganhando experiência e seus requisitos se tornarem mais claros.
<Check>
Agora você tem um framework para avaliar casos de uso CrewAI e escolher a abordagem certa de acordo com requisitos de complexidade e precisão. Isso vai ajudar você a construir aplicações de IA mais eficientes, de fácil manutenção e escaláveis.
</Check>
## Próximos Passos
- Saiba mais sobre [como criar agentes eficazes](/pt-BR/guides/agents/crafting-effective-agents)
- Explore [como construir sua primeira crew](/pt-BR/guides/crews/first-crew)
- Aprofunde-se em [gerenciamento de estado em flows](/pt-BR/guides/flows/mastering-flow-state)
- Confira os [conceitos centrais](/pt-BR/concepts/agents) para um entendimento mais aprofundado

392
docs/pt-BR/guides/crews/first-crew.mdx Normal file
View File

@@ -0,0 +1,392 @@
---
title: Monte sua Primeira Crew
description: Tutorial passo a passo para criar uma equipe colaborativa de IA que trabalha junta para resolver problemas complexos.
icon: users-gear
---
## Liberando o Poder da IA Colaborativa
Imagine ter uma equipe de agentes de IA especializados trabalhando juntos de forma harmoniosa para resolver problemas complexos, cada um contribuindo com suas habilidades únicas para alcançar um objetivo comum. Esse é o poder da CrewAI – um framework que permite criar sistemas colaborativos de IA que podem realizar tarefas muito além do que uma única IA conseguiria sozinha.
Neste guia, vamos criar uma crew de pesquisa que irá nos ajudar a pesquisar e analisar um tema, e então criar um relatório abrangente. Este exemplo prático demonstra como agentes de IA podem colaborar para realizar tarefas complexas, mas é apenas o começo do que é possível com a CrewAI.
### O que Você Vai Construir e Aprender
Ao final deste guia, você terá:
1. **Criado uma equipe de pesquisa em IA especializada** com papéis e responsabilidades distintas
2. **Orquestrado a colaboração** entre múltiplos agentes de IA
3. **Automatizado um fluxo de trabalho complexo** que envolve coleta de informações, análise e geração de relatórios
4. **Desenvolvido habilidades fundamentais** que podem ser aplicadas em projetos mais ambiciosos
Embora estejamos criando uma crew de pesquisa simples neste guia, os mesmos padrões e técnicas podem ser aplicados para criar equipes muito mais sofisticadas para tarefas como:
- Criação de conteúdo em múltiplas etapas com redatores, editores e checadores de fatos especializados
- Sistemas de atendimento ao cliente complexos com agentes de suporte em diferentes níveis
- Analistas de negócios autônomos que coletam dados, criam visualizações e geram insights
- Equipes de desenvolvimento de produto que idealizam, projetam e planejam a implementação
Vamos começar a construir sua primeira crew!
### Pré-requisitos
Antes de começar, certifique-se de que você:
1. Instalou a CrewAI seguindo o [guia de instalação](/pt-BR/installation)
2. Configurou sua chave de API de LLM no ambiente, conforme o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm)
3. Tem conhecimento básico de Python
## Passo 1: Crie um Novo Projeto CrewAI
Primeiro, vamos criar um novo projeto CrewAI usando a CLI. Este comando irá configurar toda a estrutura do projeto com os arquivos necessários, permitindo que você foque em definir seus agentes e suas tarefas, em vez de se preocupar com código boilerplate.
```bash
crewai create crew research_crew
cd research_crew
```
Isso irá gerar um projeto com a estrutura básica necessária para sua crew. A CLI cria automaticamente:
- Um diretório de projeto com os arquivos necessários
- Arquivos de configuração para agentes e tarefas
- Uma implementação básica da crew
- Um script principal para rodar a crew
<Frame caption="CrewAI Framework Overview">
<img src="/images/crews.png" alt="CrewAI Framework Overview" />
</Frame>
## Passo 2: Explore a Estrutura do Projeto
Vamos dedicar um momento para entender a estrutura do projeto criada pela CLI. A CrewAI segue boas práticas para projetos Python, tornando fácil manter e estender seu código à medida que suas crews se tornam mais complexas.
```
research_crew/
├── .gitignore
├── pyproject.toml
├── README.md
├── .env
└── src/
└── research_crew/
├── __init__.py
├── main.py
├── crew.py
├── tools/
│ ├── custom_tool.py
│ └── __init__.py
└── config/
├── agents.yaml
└── tasks.yaml
```
Esta estrutura segue as melhores práticas para projetos Python e facilita a organização do seu código. A separação dos arquivos de configuração (em YAML) do código de implementação (em Python) permite modificar o comportamento da sua crew sem alterar o código subjacente.
## Passo 3: Configure seus Agentes
Agora vem a parte divertida – definir seus agentes de IA! Na CrewAI, agentes são entidades especializadas com papéis, objetivos e históricos específicos que moldam seu comportamento. Pense neles como personagens em uma peça, cada um com sua personalidade e propósito próprios.
Para nossa crew de pesquisa, vamos criar dois agentes:
1. Um **pesquisador** que é especialista em encontrar e organizar informações
2. Um **analista** que pode interpretar os resultados da pesquisa e criar relatórios perspicazes
Vamos modificar o arquivo `agents.yaml` para definir esses agentes especializados. Certifique-se de
definir `llm` para o provedor que você está utilizando.
```yaml
# src/research_crew/config/agents.yaml
researcher:
role: >
Especialista Sênior em Pesquisa para {topic}
goal: >
Encontrar informações abrangentes e precisas sobre {topic}
com foco em desenvolvimentos recentes e insights chave
backstory: >
Você é um especialista em pesquisa experiente com talento para
encontrar informações relevantes de diversas fontes. Você se destaca em
organizar informações de forma clara e estruturada, tornando temas complexos acessíveis para outros.
llm: provider/model-id # ex: openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
analyst:
role: >
Analista de Dados e Redator de Relatórios para {topic}
goal: >
Analisar os resultados da pesquisa e criar um relatório abrangente e bem estruturado
que apresente os insights de forma clara e envolvente
backstory: >
Você é um analista habilidoso com experiência em interpretação de dados
e redação técnica. Tem talento para identificar padrões
e extrair insights relevantes dos dados de pesquisa, comunicando esses insights de forma eficaz por meio de relatórios bem elaborados.
llm: provider/model-id # ex: openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
```
Perceba como cada agente tem um papel, objetivo e histórico distintos. Esses elementos não são apenas descritivos – eles efetivamente moldam como o agente aborda suas tarefas. Ao criar cuidadosamente esses detalhes, você pode ter agentes com habilidades e perspectivas que se complementam.
## Passo 4: Defina suas Tarefas
Com nossos agentes definidos, agora precisamos atribuir tarefas específicas para eles realizarem. Tarefas na CrewAI representam o trabalho concreto que os agentes irão executar, com instruções detalhadas e saídas esperadas.
Para nossa crew de pesquisa, vamos definir duas tarefas principais:
1. Uma **tarefa de pesquisa** para coletar informações abrangentes
2. Uma **tarefa de análise** para criar um relatório com insights
Vamos modificar o arquivo `tasks.yaml`:
```yaml
# src/research_crew/config/tasks.yaml
research_task:
description: >
Realize uma pesquisa aprofundada sobre {topic}. Foque em:
1. Conceitos e definições chave
2. Desenvolvimento histórico e tendências recentes
3. Principais desafios e oportunidades
4. Aplicações relevantes ou estudos de caso
5. Perspectivas futuras e novos desenvolvimentos
Certifique-se de organizar seus achados em um formato estruturado, com seções claras.
expected_output: >
Um documento de pesquisa abrangente com seções bem organizadas cobrindo
todos os aspectos solicitados de {topic}. Inclua fatos, números
e exemplos específicos sempre que possível.
agent: researcher
analysis_task:
description: >
Analise os resultados da pesquisa e crie um relatório abrangente sobre {topic}.
Seu relatório deve:
1. Iniciar com um resumo executivo
2. Incluir todas as informações relevantes da pesquisa
3. Oferecer uma análise perspicaz de tendências e padrões
4. Apresentar recomendações ou considerações futuras
5. Estar formatado de forma profissional, clara e com títulos bem definidos
expected_output: >
Um relatório profissional, polido e estruturado sobre {topic} com apresentação dos resultados da pesquisa,
acrescentando análise e insights. O relatório deve ser bem estruturado,
incluindo resumo executivo, sessões principais e conclusão.
agent: analyst
context:
- research_task
output_file: output/report.md
```
Note o campo `context` na tarefa de análise – esse é um recurso poderoso que permite ao analista acessar a saída da tarefa de pesquisa. Isso cria um fluxo de trabalho em que a informação circula naturalmente entre os agentes, como aconteceria em uma equipe humana.
## Passo 5: Configure sua Crew
Agora é hora de juntar tudo configurando nossa crew. A crew é o container que orquestra como os agentes trabalham juntos para completar as tarefas.
Vamos modificar o arquivo `crew.py`:
```python
# src/research_crew/crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List
@CrewBase
class ResearchCrew():
"""Research crew for comprehensive topic analysis and reporting"""
agents: List[BaseAgent]
tasks: List[Task]
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'], # type: ignore[index]
verbose=True,
tools=[SerperDevTool()]
)
@agent
def analyst(self) -> Agent:
return Agent(
config=self.agents_config['analyst'], # type: ignore[index]
verbose=True
)
@task
def research_task(self) -> Task:
return Task(
config=self.tasks_config['research_task'] # type: ignore[index]
)
@task
def analysis_task(self) -> Task:
return Task(
config=self.tasks_config['analysis_task'], # type: ignore[index]
output_file='output/report.md'
)
@crew
def crew(self) -> Crew:
"""Creates the research crew"""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
Neste código, estamos:
1. Criando o agente pesquisador e equipando-o com o SerperDevTool para buscas web
2. Criando o agente analista
3. Definindo as tarefas de pesquisa e análise
4. Configurando a crew para executar as tarefas sequencialmente (o analista espera o pesquisador terminar)
É aqui que a mágica acontece – com poucas linhas de código, definimos um sistema colaborativo de IA onde agentes especializados trabalham juntos em um processo coordenado.
## Passo 6: Prepare seu Script Principal
Agora, vamos preparar o script principal que irá rodar nossa crew. É aqui que informamos o tema específico que queremos pesquisar.
```python
#!/usr/bin/env python
# src/research_crew/main.py
import os
from research_crew.crew import ResearchCrew
# Crie o diretório de saída se não existir
os.makedirs('output', exist_ok=True)
def run():
"""
Rodar a crew de pesquisa.
"""
inputs = {
'topic': 'Inteligência Artificial na Saúde'
}
# Criar e rodar a crew
result = ResearchCrew().crew().kickoff(inputs=inputs)
# Imprimir o resultado
print("\n\n=== RELATÓRIO FINAL ===\n\n")
print(result.raw)
print("\n\nRelatório salvo em output/report.md")
if __name__ == "__main__":
run()
```
Este script prepara o ambiente, define o tema de pesquisa e inicia o trabalho da crew. O poder da CrewAI fica evidente em como esse código é simples – toda a complexidade do gerenciamento de múltiplos agentes de IA é tratada pelo framework.
## Passo 7: Defina suas Variáveis de Ambiente
Crie um arquivo `.env` na raiz do seu projeto com suas chaves de API:
```sh
SERPER_API_KEY=sua_serper_api_key
# Adicione a chave de API do seu provedor também.
```
Confira o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm) para detalhes sobre como configurar o provedor de sua escolha. Você pode obter a chave da Serper em [Serper.dev](https://serper.dev/).
## Passo 8: Instale as Dependências
Instale as dependências necessárias usando a CLI da CrewAI:
```bash
crewai install
```
Este comando irá:
1. Ler as dependências da configuração do seu projeto
2. Criar um ambiente virtual se necessário
3. Instalar todos os pacotes necessários
## Passo 9: Execute sua Crew
Agora chega o momento empolgante – é hora de rodar sua crew e assistir à colaboração de IA em ação!
```bash
crewai run
```
Ao rodar esse comando, você verá sua crew ganhando vida. O pesquisador irá coletar informações sobre o tema especificado, e o analista irá criar um relatório abrangente baseado nessa pesquisa. Você poderá acompanhar em tempo real o raciocínio, as ações e os resultados dos agentes à medida que colaboram para concluir as tarefas.
## Passo 10: Revise o Resultado
Após a conclusão do trabalho da crew, você encontrará o relatório final em `output/report.md`. O relatório incluirá:
1. Um resumo executivo
2. Informações detalhadas sobre o tema
3. Análises e insights
4. Recomendações ou considerações futuras
Tire um momento para valorizar o que você realizou – você criou um sistema no qual múltiplos agentes de IA colaboraram em uma tarefa complexa, cada um contribuindo com suas habilidades especializadas para gerar um resultado maior do que qualquer agente conseguiria sozinho.
## Explorando Outros Comandos da CLI
A CrewAI oferece vários outros comandos úteis de CLI para trabalhar com crews:
```bash
# Ver todos os comandos disponíveis
crewai --help
# Rodar a crew
crewai run
# Testar a crew
crewai test
# Resetar as memórias da crew
crewai reset-memories
# Repetir a partir de uma tarefa específica
crewai replay -t <task_id>
```
## O que Mais é Possível: Além da sua Primeira Crew
O que você construiu neste guia é só o começo. As habilidades e padrões aprendidos aqui podem ser aplicados para criar sistemas de IA cada vez mais sofisticados. Veja algumas maneiras de expandir sua crew de pesquisa básica:
### Expandindo sua Crew
Você pode adicionar mais agentes especializados à sua crew:
- Um **checador de fatos** para verificar as informações encontradas
- Um **visualizador de dados** para criar gráficos e tabelas
- Um **especialista de domínio** com conhecimento aprofundado em uma área específica
- Um **crítico** para identificar pontos fracos na análise
### Adicionando Ferramentas e Capacidades
Você pode potencializar seus agentes com ferramentas adicionais:
- Ferramentas de navegação web para pesquisa em tempo real
- Ferramentas para CSV ou bancos de dados para análise de dados
- Ferramentas de execução de código para processamento de dados
- Conexões de API com serviços externos
### Criando Fluxos de Trabalho Mais Complexos
Você pode implementar processos mais sofisticados:
- Processos hierárquicos em que agentes gestores delegam para agentes
- Processos iterativos com loops de feedback para refinamento
- Processos paralelos onde múltiplos agentes trabalham simultaneamente
- Processos dinâmicos que se adaptam a resultados intermediários
### Aplicando em Diferentes Domínios
Os mesmos padrões podem ser aplicados para criar crews para:
- **Criação de conteúdo:** Redatores, editores, checadores de fatos e designers trabalhando juntos
- **Atendimento ao cliente:** Agentes de triagem, especialistas e controle de qualidade atuando colaborativamente
- **Desenvolvimento de produto:** Pesquisadores, designers e planejadores trabalhando em conjunto
- **Análise de dados:** Coletores de dados, analistas e especialistas em visualização
## Próximos Passos
Agora que você montou sua primeira crew, você pode:
1. Experimentar diferentes configurações e personalidades de agentes
2. Testar estruturas de tarefas e fluxos de trabalho mais complexos
3. Implementar ferramentas customizadas para dar novas capacidades aos agentes
4. Aplicar sua crew em outros temas ou domínios de problemas
5. Explorar [CrewAI Flows](/pt-BR/guides/flows/first-flow) para fluxos de trabalho avançados usando programação procedural
<Check>
Parabéns! Você construiu com sucesso sua primeira crew com o CrewAI, capaz de pesquisar e analisar qualquer tema que desejar. Essa experiência fundamental lhe deu as habilidades para criar sistemas de IA cada vez mais sofisticados, aptos a encarar problemas complexos e de múltiplas etapas por meio da inteligência colaborativa.
</Check>

461
docs/pt-BR/guides/flows/first-flow.mdx Normal file
View File

@@ -0,0 +1,461 @@
---
title: Construa Seu Primeiro Flow
description: Aprenda como criar fluxos de trabalho estruturados e orientados a eventos com controle preciso sobre a execução.
icon: diagram-project
---
## Assumindo o Controle de Workflows de IA com Flows
Os Flows do CrewAI representam o próximo nível em orquestração de IA – combinando o poder colaborativo de equipes de agentes de IA com a precisão e flexibilidade da programação procedural. Enquanto os crews se destacam em colaboração de agentes, os flows dão a você controle detalhado sobre exatamente como e quando diferentes componentes do seu sistema de IA interagem.
Neste guia, vamos percorrer a criação de um poderoso CrewAI Flow que gera um guia de aprendizado abrangente sobre qualquer tema. Este tutorial demonstrará como os Flows oferecem controle estruturado e orientado a eventos sobre seus workflows de IA ao combinar código regular, chamadas diretas a LLM e processamento baseado em crews.
### O Que Torna os Flows Poderosos
Com flows, você pode:
1. **Combinar diferentes padrões de interação com IA** – Use crews para tarefas colaborativas complexas, chamadas diretas às LLMs para operações mais simples, e código regular para lógica procedural.
2. **Construir sistemas orientados a eventos** – Defina como os componentes respondem a eventos e mudanças de dados específicos.
3. **Manter estado entre componentes** – Compartilhe e transforme dados entre diferentes partes da sua aplicação.
4. **Integrar com sistemas externos** – Conecte seu fluxo de trabalho de IA com bancos de dados, APIs e interfaces de usuário de forma transparente.
5. **Criar caminhos de execução complexos** – Projete ramificações condicionais, processamento paralelo e workflows dinâmicos.
### O Que Você Vai Construir e Aprender
Ao final deste guia, você terá:
1. **Criado um sistema sofisticado de geração de conteúdo** que combina entrada do usuário, planejamento por IA e criação de conteúdo multiagente.
2. **Orquestrado o fluxo de informações** entre diferentes componentes do seu sistema.
3. **Implementado uma arquitetura orientada a eventos** onde cada etapa responde à conclusão das etapas anteriores.
4. **Construído uma base para aplicações de IA mais complexas** que você pode expandir e personalizar.
Este flow de criação de guia demonstra padrões fundamentais que podem ser aplicados para criar aplicações muito mais avançadas, como:
- Assistentes de IA interativos que combinam múltiplos subsistemas especializados.
- Pipelines de processamento de dados complexos com transformações aprimoradas por IA.
- Agentes autônomos integrados a serviços e APIs externas.
- Sistemas de tomada de decisão em múltiplas etapas com processos envolvendo humanos no loop.
Vamos começar e construir seu primeiro flow!
## Pré-requisitos
Antes de começar, certifique-se de ter:
1. Instalado o CrewAI seguindo o [guia de instalação](/pt-BR/installation)
2. Configurado sua chave de API LLM no ambiente, conforme o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm)
3. Conhecimentos básicos de Python
## Passo 1: Crie um Novo Projeto de CrewAI Flow
Primeiro, vamos criar um novo projeto de Flow do CrewAI usando a CLI. Este comando configura um projeto com todos os diretórios necessários e arquivos de template para seu flow.
```bash
crewai create flow guide_creator_flow
cd guide_creator_flow
```
Isso gerará um projeto com a estrutura básica necessária para seu flow.
<Frame caption="Visão Geral do Framework CrewAI">
<img src="/images/flows.png" alt="CrewAI Framework Overview" />
</Frame>
## Passo 2: Entendendo a Estrutura do Projeto
O projeto gerado possui a seguinte estrutura. Reserve um momento para conhecê-la, pois isso ajudará você a criar flows mais complexos no futuro.
```
guide_creator_flow/
├── .gitignore
├── pyproject.toml
├── README.md
├── .env
├── main.py
├── crews/
│ └── poem_crew/
│ ├── config/
│ │ ├── agents.yaml
│ │ └── tasks.yaml
│ └── poem_crew.py
└── tools/
└── custom_tool.py
```
Esta estrutura oferece uma separação clara entre os diferentes componentes do seu flow:
- A lógica principal do flow no arquivo `main.py`
- Crews especializados no diretório `crews`
- Ferramentas customizadas no diretório `tools`
Vamos modificar esta estrutura para criar nosso flow de criação de guias, que irá orquestrar o processo de geração de guias de aprendizagem abrangentes.
## Passo 3: Adicione um Crew de Redator de Conteúdo
Nosso flow precisará de um crew especializado para lidar com o processo de criação de conteúdo. Vamos usar a CLI do CrewAI para adicionar um crew de redatores de conteúdo:
```bash
crewai flow add-crew content-crew
```
Este comando cria automaticamente os diretórios e arquivos de template necessários para seu crew. O crew de redatores será responsável por escrever e revisar seções do nosso guia, trabalhando dentro do flow orquestrado pela aplicação principal.
## Passo 4: Configure o Crew de Redator de Conteúdo
Agora, vamos modificar os arquivos gerados para o crew de redatores. Vamos configurar dois agentes especializados – um escritor e um revisor – que irão colaborar para criar um conteúdo de alta qualidade para o nosso guia.
1. Primeiro, atualize o arquivo de configuração de agents para definir a equipe de criação de conteúdo:
Lembre-se de configurar o `llm` com o provedor que está utilizando.
```yaml
# src/guide_creator_flow/crews/content_crew/config/agents.yaml
content_writer:
role: >
Redator de Conteúdo Educacional
goal: >
Criar conteúdo envolvente e informativo que explique completamente o tema proposto
e forneça insights valiosos ao leitor
backstory: >
Você é um talentoso escritor educacional com experiência em criar conteúdo claro
e atraente. Você tem facilidade para explicar conceitos complexos em linguagem acessível
e organizar as informações de forma a ajudar o leitor a construir seu entendimento.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
content_reviewer:
role: >
Revisor(a) e Editor(a) de Conteúdo Educacional
goal: >
Garantir que o conteúdo seja preciso, abrangente, bem estruturado e mantenha
consistência com as seções previamente escritas
backstory: >
Você é um editor(a) meticuloso(a) com anos de experiência revisando conteúdo educacional.
Tem atenção aos detalhes, clareza e coesão. Você se destaca em aprimorar conteúdo
mantendo o estilo do autor original e garantindo qualidade consistente em várias seções.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
```
Essas definições de agents estabelecem papéis e perspectivas especializadas que irão moldar como nossos agentes de IA abordam a criação de conteúdo. Note como cada agent possui um propósito e expertise distintos.
2. Em seguida, atualize o arquivo de configuração de tarefas para definir as tarefas específicas de escrita e revisão:
```yaml
# src/guide_creator_flow/crews/content_crew/config/tasks.yaml
write_section_task:
description: >
Escreva uma seção abrangente sobre o tema: "{section_title}"
Descrição da seção: {section_description}
Público-alvo: {audience_level} aprendizes
Seu conteúdo deve:
1. Começar com uma breve introdução ao tema da seção
2. Explicar claramente todos os conceitos principais com exemplos
3. Incluir aplicações práticas ou exercícios onde apropriado
4. Terminar com um resumo dos pontos principais
5. Ter aproximadamente 500-800 palavras
Formate seu conteúdo em Markdown com títulos, listas e ênfase apropriados.
Seções previamente escritas:
{previous_sections}
Certifique-se de que seu conteúdo mantenha consistência com as seções já escritas
e amplie os conceitos que já foram explicados.
expected_output: >
Uma seção bem estruturada e abrangente em formato Markdown que explique
totalmente o tema e é apropriada para o público-alvo.
agent: content_writer
review_section_task:
description: >
Revise e melhore a seguinte seção sobre "{section_title}":
{draft_content}
Público-alvo: {audience_level} aprendizes
Seções previamente escritas:
{previous_sections}
Sua revisão deve:
1. Corrigir qualquer erro gramatical ou de ortografia
2. Melhorar clareza e legibilidade
3. Garantir que o conteúdo seja abrangente e preciso
4. Verificar a consistência com as seções já escritas
5. Aprimorar a estrutura e o fluxo
6. Adicionar qualquer informação-chave ausente
Forneça a versão aprimorada da seção em formato Markdown.
expected_output: >
Uma versão melhorada e refinada da seção, mantendo a estrutura original,
mas aprimorando clareza, precisão e consistência.
agent: content_reviewer
context:
- write_section_task
```
Essas definições de tarefas fornecem instruções detalhadas para nossos agents, garantindo que eles produzam conteúdo que atenda aos padrões de qualidade. Observe como o parâmetro `context` na tarefa de revisão cria um fluxo onde o revisor tem acesso à produção do redator.
3. Agora, atualize o arquivo de implementação do crew para definir como nossos agents e tasks trabalham juntos:
```python
# src/guide_creator_flow/crews/content_crew/content_crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List
@CrewBase
class ContentCrew():
"""Crew de redação de conteúdo"""
agents: List[BaseAgent]
tasks: List[Task]
@agent
def content_writer(self) -> Agent:
return Agent(
config=self.agents_config['content_writer'], # type: ignore[index]
verbose=True
)
@agent
def content_reviewer(self) -> Agent:
return Agent(
config=self.agents_config['content_reviewer'], # type: ignore[index]
verbose=True
)
@task
def write_section_task(self) -> Task:
return Task(
config=self.tasks_config['write_section_task'] # type: ignore[index]
)
@task
def review_section_task(self) -> Task:
return Task(
config=self.tasks_config['review_section_task'], # type: ignore[index]
context=[self.write_section_task()]
)
@crew
def crew(self) -> Crew:
"""Cria o crew de redação de conteúdo"""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
Essa definição de crew estabelece o relacionamento entre nossos agents e tasks, definindo um processo sequencial onde o redator cria o rascunho e o revisor o aprimora. Embora este crew possa funcionar de forma independente, em nosso flow ele será orquestrado como parte de um sistema maior.
## Passo 5: Crie o Flow
Agora vem a parte emocionante – criar o flow que irá orquestrar todo o processo de criação do guia. Aqui iremos combinar código Python regular, chamadas diretas a LLM e nosso crew de criação de conteúdo em um sistema coeso.
Nosso flow irá:
1. Obter a entrada do usuário sobre o tema e nível do público
2. Fazer uma chamada direta à LLM para criar um roteiro estruturado do guia
3. Processar cada seção sequencialmente usando o crew de redatores
4. Combinar tudo em um documento final abrangente
Vamos criar nosso flow no arquivo `main.py`:
```python
# [CÓDIGO NÃO TRADUZIDO, MANTER COMO ESTÁ]
```
Vamos analisar o que está acontecendo neste flow:
1. Definimos modelos Pydantic para dados estruturados, garantindo segurança de tipos e representação clara dos dados.
2. Criamos uma classe de estado para manter dados entre os diferentes passos do flow.
3. Implementamos três etapas principais para o flow:
- Obtenção da entrada do usuário com o decorator `@start()`
- Criação do roteiro do guia com uma chamada direta à LLM
- Processamento das seções com nosso crew de conteúdo
4. Usamos o decorator `@listen()` para estabelecer relações orientadas a eventos entre as etapas
Este é o poder dos flows – combinar diferentes tipos de processamento (interação com usuário, chamadas diretas a IA, tarefas colaborativas com crews) em um sistema orientado a eventos e coeso.
## Passo 6: Configure suas Variáveis de Ambiente
Crie um arquivo `.env` na raiz do projeto com suas chaves de API. Veja o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm) para detalhes sobre como configurar o provedor.
```sh .env
OPENAI_API_KEY=sua_chave_openai
# ou
GEMINI_API_KEY=sua_chave_gemini
# ou
ANTHROPIC_API_KEY=sua_chave_anthropic
```
## Passo 7: Instale as Dependências
Instale as dependências necessárias:
```bash
crewai install
```
## Passo 8: Execute Seu Flow
Agora é hora de ver seu flow em ação! Execute-o usando a CLI do CrewAI:
```bash
crewai flow kickoff
```
Quando você rodar esse comando, verá seu flow ganhando vida:
1. Ele solicitará um tema e o nível do público para você
2. Criará um roteiro estruturado para o seu guia
3. Processará cada seção, com o redator e o revisor colaborando em cada uma
4. Por fim, irá compilar tudo em um guia abrangente
Isso demonstra o poder dos flows para orquestrar processos complexos envolvendo múltiplos componentes, tanto de IA quanto não-IA.
## Passo 9: Visualize Seu Flow
Uma das funcionalidades mais poderosas dos flows é a possibilidade de visualizar sua estrutura:
```bash
crewai flow plot
```
Isso irá criar um arquivo HTML que mostra a estrutura do seu flow, incluindo os relacionamentos entre etapas e o fluxo de dados. Essa visualização pode ser inestimável para entender e depurar flows complexos.
## Passo 10: Revise o Resultado
Depois que o flow finalizar, você encontrará dois arquivos no diretório `output`:
1. `guide_outline.json`: Contém o roteiro estruturado do guia
2. `complete_guide.md`: O guia abrangente com todas as seções
Reserve um momento para revisar esses arquivos e apreciar o que você construiu – um sistema que combina entrada do usuário, interações diretas com IA e trabalho colaborativo de agents para produzir um output complexo e de alta qualidade.
## A Arte do Possível: Além do Seu Primeiro Flow
O que você aprendeu neste guia é uma base para criar sistemas de IA muito mais sofisticados. Veja algumas formas de expandir este flow básico:
### Aprimorando a Interação com o Usuário
Você pode criar flows mais interativos com:
- Interfaces web para entrada e saída de dados
- Atualizações em tempo real de progresso
- Loops de feedback e refinamento interativos
- Interações multi-stage com o usuário
### Adicionando Mais Etapas de Processamento
Você pode expandir seu flow com etapas adicionais para:
- Pesquisa antes da criação do roteiro
- Geração de imagens para ilustrações
- Geração de snippets de código para guias técnicos
- Garantia de qualidade e checagem final de fatos
### Criando Flows Mais Complexos
Você pode implementar padrões de flow mais sofisticados:
- Ramificações condicionais com base na preferência do usuário ou tipo de conteúdo
- Processamento paralelo de seções independentes
- Loops de refinamento iterativo com feedback
- Integração a APIs e serviços externos
### Aplicando a Diferentes Domínios
Os mesmos padrões podem ser usados para criar flows de:
- **Narrativas interativas**: criação de histórias personalizadas com base na entrada do usuário
- **Inteligência de negócios**: processamento de dados, geração de insights e criação de relatórios
- **Desenvolvimento de produtos**: facilitação de ideação, design e planejamento
- **Sistemas educacionais**: criação de experiências de aprendizagem personalizadas
## Principais Funcionalidades Demonstradas
Este flow de criação de guia demonstra diversos recursos poderosos do CrewAI:
1. **Interação com o usuário**: O flow coleta input diretamente do usuário
2. **Chamadas diretas à LLM**: Usa a classe LLM para interações eficientes e direcionadas com IA
3. **Dados estruturados com Pydantic**: Usa Pydantic para garantir segurança de tipos
4. **Processamento sequencial com contexto**: Escreve seções em ordem, fornecendo as anteriores como contexto
5. **Crews multiagentes**: Utiliza agents especializados (redator e revisor) para criação de conteúdo
6. **Gerenciamento de estado**: Mantém estado entre diferentes etapas do processo
7. **Arquitetura orientada a eventos**: Usa o decorator `@listen` para responder a eventos
## Entendendo a Estrutura do Flow
Vamos decompor os principais componentes dos flows para ajudá-lo a entender como construir o seu:
### 1. Chamadas Diretas à LLM
Flows permitem que você faça chamadas diretas a modelos de linguagem quando precisa de respostas simples e estruturadas:
```python
llm = LLM(
model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude...
response_format=GuideOutline
)
response = llm.call(messages=messages)
```
Isso é mais eficiente do que usar um crew quando você precisa de um output específico e estruturado.
### 2. Arquitetura Orientada a Eventos
Flows usam decorators para estabelecer relações entre componentes:
```python
@start()
def get_user_input(self):
# Primeira etapa no flow
# ...
@listen(get_user_input)
def create_guide_outline(self, state):
# Esta roda quando get_user_input é concluída
# ...
```
Isso cria uma estrutura clara e declarativa para sua aplicação.
### 3. Gerenciamento de Estado
Flows mantêm o estado entre as etapas, facilitando o compartilhamento de dados:
```python
class GuideCreatorState(BaseModel):
topic: str = ""
audience_level: str = ""
guide_outline: GuideOutline = None
sections_content: Dict[str, str] = {}
```
Isso fornece uma maneira segura e tipada de rastrear e transformar dados ao longo do flow.
### 4. Integração com Crews
Flows podem integrar crews para tarefas colaborativas complexas:
```python
result = ContentCrew().crew().kickoff(inputs={
"section_title": section.title,
# ...
})
```
Assim, você usa a ferramenta certa para cada parte da aplicação – chamadas diretas para tarefas simples e crews para colaboração avançada.
## Próximos Passos
Agora que você construiu seu primeiro flow, pode:
1. Experimentar estruturas e padrões mais complexos de flow
2. Testar o uso do `@router()` para criar ramificações condicionais em seus flows
3. Explorar as funções `and_` e `or_` para execuções paralelas e mais complexas
4. Conectar seu flow a APIs externas, bancos de dados ou interfaces de usuário
5. Combinar múltiplos crews especializados em um único flow
<Check>
Parabéns! Você construiu seu primeiro CrewAI Flow que combina código regular, chamadas diretas a LLM e processamento baseado em crews para criar um guia abrangente. Essas habilidades fundamentais permitem criar aplicações de IA cada vez mais sofisticadas, capazes de resolver problemas complexos de múltiplas etapas por meio de controle procedural e inteligência colaborativa.
</Check>

294
docs/pt-BR/guides/flows/mastering-flow-state.mdx Normal file
View File

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

200
docs/pt-BR/installation.mdx Normal file
View File

@@ -0,0 +1,200 @@
---
title: Instalação
description: Comece a usar o CrewAI - Instale, configure e crie seu primeiro crew de IA
icon: wrench
---
## Tutorial em Vídeo
Assista a este tutorial em vídeo para uma demonstração passo a passo do processo de instalação:
<iframe
width="100%"
height="400"
src="https://www.youtube.com/embed/-kSOTtYzgEw"
title="CrewAI Installation Guide"
frameborder="0"
style={{ borderRadius: '10px' }}
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
## Tutorial em Texto
<Note>
**Requisitos de Versão do Python**
CrewAI requer `Python >=3.10 e <3.14`. Veja como verificar sua versão:
```bash
python3 --version
```
Se você precisar atualizar o Python, acesse [python.org/downloads](https://python.org/downloads)
</Note>
CrewAI utiliza o `uv` como ferramenta de gerenciamento de dependências e pacotes. Ele simplifica a configuração e execução do projeto, oferecendo uma experiência fluida.
Se você ainda não instalou o `uv`, siga o **passo 1** para instalá-lo rapidamente em seu sistema, caso contrário, avance para o **passo 2**.
<Steps>
<Step title="Instale o uv">
- **No macOS/Linux:**
Use `curl` para baixar o script e executá-lo com `sh`:
```shell
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Se seu sistema não possuir `curl`, você pode usar `wget`:
```shell
wget -qO- https://astral.sh/uv/install.sh | sh
```
- **No Windows:**
Use `irm` para baixar o script e `iex` para executá-lo:
```shell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
Caso enfrente algum problema, consulte o [guia de instalação do UV](https://docs.astral.sh/uv/getting-started/installation/) para mais informações.
</Step>
<Step title="Instale o CrewAI 🚀">
- Execute o seguinte comando para instalar o CLI do `crewai`:
```shell
uv tool install crewai
```
<Warning>
Se aparecer um aviso relacionado ao `PATH`, execute este comando para atualizar seu shell:
```shell
uv tool update-shell
```
</Warning>
<Warning>
Se você encontrar o erro de build ao instalar `chroma-hnswlib==0.7.6` (`fatal error C1083: Cannot open include file: 'float.h'`) no Windows, instale o (Visual Studio Build Tools)[https://visualstudio.microsoft.com/downloads/] com o *Desenvolvimento de Desktop com C++*.
</Warning>
- Para verificar se o `crewai` está instalado, execute:
```shell
uv tool list
```
- Você deverá ver algo assim:
```shell
crewai v0.102.0
- crewai
```
- Caso precise atualizar o `crewai`, execute:
```shell
uv tool install crewai --upgrade
```
<Check>Instalação realizada com sucesso! Você está pronto para criar seu primeiro crew! 🎉</Check>
</Step>
</Steps>
# Criando um Projeto CrewAI
Recomendamos utilizar o template de scaffolding `YAML` para uma abordagem estruturada na definição dos agentes e tarefas. Veja como começar:
<Steps>
<Step title="Gerar Scaffolding do Projeto">
- Execute o comando CLI do `crewai`:
```shell
crewai create crew <your_project_name>
```
- Isso criará um novo projeto com a seguinte estrutura:
<Frame>
```
my_project/
├── .gitignore
├── knowledge/
├── pyproject.toml
├── README.md
├── .env
└── src/
└── my_project/
├── __init__.py
├── main.py
├── crew.py
├── tools/
│ ├── custom_tool.py
│ └── __init__.py
└── config/
├── agents.yaml
└── tasks.yaml
```
</Frame>
</Step>
<Step title="Personalize Seu Projeto">
- Seu projeto conterá estes arquivos essenciais:
| Arquivo | Finalidade |
| --- | --- |
| `agents.yaml` | Defina seus agentes de IA e seus papéis |
| `tasks.yaml` | Configure as tarefas e fluxos de trabalho dos agentes |
| `.env` | Armazene chaves de API e variáveis de ambiente |
| `main.py` | Ponto de entrada e fluxo de execução do projeto |
| `crew.py` | Orquestração e coordenação do crew |
| `tools/` | Diretório para ferramentas customizadas dos agentes |
| `knowledge/` | Diretório para base de conhecimento |
- Comece editando `agents.yaml` e `tasks.yaml` para definir o comportamento do seu crew.
- Mantenha informações sensíveis como chaves de API no arquivo `.env`.
</Step>
<Step title="Execute seu Crew">
- Antes de rodar seu crew, execute:
```bash
crewai install
```
- Se precisar instalar pacotes adicionais, utilize:
```shell
uv add <package-name>
```
- Para rodar seu crew, execute o seguinte comando na raiz do seu projeto:
```bash
crewai run
```
</Step>
</Steps>
## Opções de Instalação Enterprise
<Note type="info">
Para equipes e organizações, o CrewAI oferece opções de implantação corporativa que eliminam a complexidade da configuração:
### CrewAI Enterprise (SaaS)
- Zero instalação necessária - basta se cadastrar gratuitamente em [app.crewai.com](https://app.crewai.com)
- Atualizações e manutenção automáticas
- Infraestrutura e escalabilidade gerenciadas
- Construa crews sem código
### CrewAI Factory (Auto-Hospedado)
- Implantação containerizada para sua infraestrutura
- Compatível com qualquer hyperscaler, incluindo ambientes on-premises
- Integração com seus sistemas de segurança existentes
<Card title="Explore as Opções Enterprise" icon="building" href="https://crewai.com/enterprise">
Saiba mais sobre as soluções enterprise do CrewAI e agende uma demonstração
</Card>
</Note>
## Próximos Passos
<CardGroup cols={2}>
<Card
title="Construa Seu Primeiro Agente"
icon="code"
href="/pt-BR/quickstart"
>
Siga nosso guia de início rápido para criar seu primeiro agente CrewAI e obter experiência prática.
</Card>
<Card
title="Junte-se à Comunidade"
icon="comments"
href="https://community.crewai.com"
>
Conecte-se com outros desenvolvedores, obtenha ajuda e compartilhe suas experiências com o CrewAI.
</Card>
</CardGroup>

164
docs/pt-BR/introduction.mdx Normal file
View File

@@ -0,0 +1,164 @@
---
title: Introdução
description: Construa equipes de agentes de IA que trabalham juntas para resolver tarefas complexas
icon: handshake
---
# O que é CrewAI?
**CrewAI é um framework Python enxuto e ultrarrápido, construído totalmente do zero—completamente independente do LangChain ou de outros frameworks de agentes.**
O CrewAI capacita desenvolvedores tanto com simplicidade de alto nível quanto com controle detalhado de baixo nível, ideal para criar agentes de IA autônomos sob medida para qualquer cenário:
- **[Crews do CrewAI](/pt-BR/guides/crews/first-crew)**: Otimizados para autonomia e inteligência colaborativa, permitindo criar equipes de IA onde cada agente possui funções, ferramentas e objetivos específicos.
- **[Flows do CrewAI](/pt-BR/guides/flows/first-flow)**: Proporcionam controle granular, orientado por eventos, com chamadas LLM individuais para uma orquestração precisa das tarefas, além de suportar Crews nativamente.
Com mais de 100.000 desenvolvedores certificados em nossos cursos comunitários, o CrewAI está se tornando rapidamente o padrão para automação de IA pronta para empresas.
## Como funcionam os Crews
<Note>
Assim como uma empresa possui departamentos (Vendas, Engenharia, Marketing) trabalhando juntos sob uma liderança para atingir objetivos de negócio, o CrewAI ajuda você a criar uma “organização” de agentes de IA com funções especializadas colaborando para realizar tarefas complexas.
</Note>
<Frame caption="Visão Geral do Framework CrewAI">
<img src="/images/crews.png" alt="Visão Geral do Framework CrewAI" />
</Frame>
| Componente | Descrição | Principais Funcionalidades |
|:-----------|:-----------:|:-------------------------|
| **Crew** | Organização de mais alto nível | • Gerencia equipes de agentes de IA<br/>• Supervisiona fluxos de trabalho<br/>• Garante colaboração<br/>• Entrega resultados |
| **Agentes de IA** | Membros especializados da equipe | • Possuem funções específicas (pesquisador, escritor)<br/>• Utilizam ferramentas designadas<br/>• Podem delegar tarefas<br/>• Tomam decisões autônomas |
| **Process** | Sistema de gestão do fluxo de trabalho | • Define padrões de colaboração<br/>• Controla designação de tarefas<br/>• Gerencia interações<br/>• Garante execução eficiente |
| **Tasks** | Atribuições individuais | • Objetivos claros<br/>• Utilizam ferramentas específicas<br/>• Alimentam processos maiores<br/>• Geram resultados acionáveis |
### Como tudo trabalha junto
1. O **Crew** organiza toda a operação
2. **Agentes de IA** realizam tarefas especializadas
3. O **Process** garante colaboração fluida
4. **Tasks** são concluídas para alcançar o objetivo
## Principais Funcionalidades
<CardGroup cols={2}>
<Card title="Agentes Baseados em Funções" icon="users">
Crie agentes especializados com funções, conhecimentos e objetivos definidos – de pesquisadores e analistas a escritores
</Card>
<Card title="Ferramentas Flexíveis" icon="screwdriver-wrench">
Equipe os agentes com ferramentas e APIs personalizadas para interagir com serviços e fontes de dados externas
</Card>
<Card title="Colaboração Inteligente" icon="people-arrows">
Agentes trabalham juntos, compartilhando insights e coordenando tarefas para conquistar objetivos complexos
</Card>
<Card title="Gerenciamento de Tarefas" icon="list-check">
Defina fluxos de trabalho sequenciais ou paralelos, com agentes lidando automaticamente com dependências entre tarefas
</Card>
</CardGroup>
## Como funcionam os Flows
<Note>
Enquanto Crews se destacam na colaboração autônoma, Flows proporcionam automações estruturadas, oferecendo controle granular sobre a execução dos fluxos de trabalho. Flows garantem execução confiável, segura e eficiente, lidando com lógica condicional, loops e gerenciamento dinâmico de estados com precisão. Flows se integram perfeitamente com Crews, permitindo equilibrar alta autonomia com controle rigoroso.
</Note>
<Frame caption="Visão Geral do Framework CrewAI">
<img src="/images/flows.png" alt="Visão Geral do Framework CrewAI" />
</Frame>
| Componente | Descrição | Principais Funcionalidades |
|:-----------|:-----------:|:-------------------------|
| **Flow** | Orquestração de fluxo de trabalho estruturada | • Gerencia caminhos de execução<br/>• Lida com transições de estado<br/>• Controla a sequência de tarefas<br/>• Garante execução confiável |
| **Events** | Gatilhos para ações nos fluxos | • Iniciam processos específicos<br/>• Permitem respostas dinâmicas<br/>• Suportam ramificações condicionais<br/>• Adaptam-se em tempo real |
| **States** | Contextos de execução dos fluxos | • Mantêm dados de execução<br/>• Permitem persistência<br/>• Suportam retomada<br/>• Garantem integridade na execução |
| **Crew Support** | Aprimora automação de fluxos | • Injeta autonomia quando necessário<br/>• Complementa fluxos estruturados<br/>• Equilibra automação e inteligência<br/>• Permite tomada de decisão adaptativa |
### Capacidades-Chave
<CardGroup cols={2}>
<Card title="Orquestração Orientada por Eventos" icon="bolt">
Defina caminhos de execução precisos respondendo dinamicamente a eventos
</Card>
<Card title="Controle Detalhado" icon="sliders">
Gerencie estados de fluxo de trabalho e execução condicional de forma segura e eficiente
</Card>
<Card title="Integração Nativa com Crew" icon="puzzle-piece">
Combine de forma simples com Crews para maior autonomia e inteligência
</Card>
<Card title="Execução Determinística" icon="route">
Garanta resultados previsíveis com controle explícito de fluxo e tratamento de erros
</Card>
</CardGroup>
## Quando usar Crews versus Flows
<Note>
Entender quando utilizar [Crews](/pt-BR/guides/crews/first-crew) ou [Flows](/pt-BR/guides/flows/first-flow) é fundamental para maximizar o potencial do CrewAI em suas aplicações.
</Note>
| Caso de uso | Abordagem recomendada | Por quê? |
|:------------|:---------------------|:---------|
| **Pesquisa aberta** | [Crews](/pt-BR/guides/crews/first-crew) | Quando as tarefas exigem criatividade, exploração e adaptação |
| **Geração de conteúdo** | [Crews](/pt-BR/guides/crews/first-crew) | Para criação colaborativa de artigos, relatórios ou materiais de marketing |
| **Fluxos de decisão** | [Flows](/pt-BR/guides/flows/first-flow) | Quando é necessário caminhos de decisão previsíveis, auditáveis e com controle preciso |
| **Orquestração de APIs** | [Flows](/pt-BR/guides/flows/first-flow) | Para integração confiável com múltiplos serviços externos em sequência específica |
| **Aplicações híbridas** | Abordagem combinada | Use [Flows](/pt-BR/guides/flows/first-flow) para orquestrar o processo geral com [Crews](/pt-BR/guides/crews/first-crew) lidando com subtarefas complexas |
### Framework de Decisão
- **Escolha [Crews](/pt-BR/guides/crews/first-crew) quando:** Precisa de resolução autônoma de problemas, colaboração criativa ou tarefas exploratórias
- **Escolha [Flows](/pt-BR/guides/flows/first-flow) quando:** Requer resultados determinísticos, auditabilidade ou controle preciso sobre a execução
- **Combine ambos quando:** Sua aplicação precisa de processos estruturados e também de bolsões de inteligência autônoma
## Por que escolher o CrewAI?
- 🧠 **Operação Autônoma**: Agentes tomam decisões inteligentes com base em suas funções e nas ferramentas disponíveis
- 📝 **Interação Natural**: Agentes se comunicam e colaboram como membros humanos de uma equipe
- 🛠️ **Design Extensível**: Fácil de adicionar novas ferramentas, funções e capacidades
- 🚀 **Pronto para Produção**: Construído para confiabilidade e escalabilidade em aplicações reais
- 🔒 **Foco em Segurança**: Desenvolvido para atender requisitos de segurança empresarial
- 💰 **Custo-Efetivo**: Otimizado para minimizar o uso de tokens e chamadas de API
## Pronto para começar a construir?
<CardGroup cols={2}>
<Card
title="Crie Seu Primeiro Crew"
icon="users-gear"
href="/pt-BR/guides/crews/first-crew"
>
Tutorial passo a passo para criar uma equipe de IA colaborativa que trabalha junto para resolver problemas complexos.
</Card>
<Card
title="Crie Seu Primeiro Flow"
icon="diagram-project"
href="/pt-BR/guides/flows/first-flow"
>
Aprenda a criar fluxos de trabalho estruturados e orientados por eventos com controle preciso de execução.
</Card>
</CardGroup>
<CardGroup cols={3}>
<Card
title="Instale o CrewAI"
icon="wrench"
href="/pt-BR/installation"
>
Comece a usar o CrewAI em seu ambiente de desenvolvimento.
</Card>
<Card
title="Primeiros Passos"
icon="bolt"
href="/pt-BR/quickstart"
>
Siga nosso guia rápido para criar seu primeiro agente CrewAI e colocar a mão na massa.
</Card>
<Card
title="Junte-se à Comunidade"
icon="comments"
href="https://community.crewai.com"
>
Conecte-se com outros desenvolvedores, obtenha ajuda e compartilhe suas experiências com o CrewAI.
</Card>
</CardGroup>

60
docs/pt-BR/learn/before-and-after-kickoff-hooks.mdx Normal file
View File

@@ -0,0 +1,60 @@
---
title: Hooks Antes e Depois do Kickoff
description: Aprenda a usar hooks antes e depois do kickoff em CrewAI
---
O CrewAI fornece hooks que permitem executar código antes e depois do kickoff de uma crew. Esses hooks são úteis para pré-processar entradas ou pós-processar resultados.
## Hook Antes do Kickoff
O hook antes do kickoff é executado antes da crew iniciar suas tarefas. Ele recebe o dicionário de entradas e pode modificá-lo antes de passá-lo para a crew. Você pode usar esse hook para configurar seu ambiente, carregar dados necessários ou pré-processar suas entradas. Isso é útil em cenários onde os dados de entrada podem precisar de enriquecimento ou validação antes de serem processados pela crew.
Aqui está um exemplo de como definir uma função antes do kickoff em seu `crew.py`:
```python
from crewai import CrewBase
from crewai.project import before_kickoff
@CrewBase
class MyCrew:
@before_kickoff
def prepare_data(self, inputs):
# Preprocess or modify inputs
inputs['processed'] = True
return inputs
#...
```
Neste exemplo, a função prepare_data modifica as entradas adicionando um novo par chave-valor indicando que as entradas foram processadas.
## Hook Depois do Kickoff
O hook depois do kickoff é executado após a crew completar suas tarefas. Ele recebe o objeto de resultado, que contém as saídas da execução da crew. Este hook é ideal para pós-processar resultados, como log, transformação de dados ou análise adicional.
Veja como você pode definir uma função depois do kickoff em seu `crew.py`:
```python
from crewai import CrewBase
from crewai.project import after_kickoff
@CrewBase
class MyCrew:
@after_kickoff
def log_results(self, result):
# Log or modify the results
print("Crew execution completed with result:", result)
return result
# ...
```
Na função `log_results`, os resultados da execução da crew são simplesmente impressos. Você pode estender isso para realizar operações mais complexas, como enviar notificações ou integrar com outros serviços.
## Utilizando Ambos os Hooks
Ambos os hooks podem ser usados juntos para oferecer um processo completo de preparação e finalização na execução da sua crew. Eles são particularmente úteis para manter uma arquitetura de código limpa, separando responsabilidades e melhorando a modularidade das suas implementações com CrewAI.
## Conclusão
Os hooks antes e depois do kickoff em CrewAI oferecem formas poderosas de interagir com o ciclo de vida da execução de uma crew. Ao entender e utilizar esses hooks, você pode aumentar significativamente a robustez e flexibilidade dos seus agentes de IA.

441
docs/pt-BR/learn/bring-your-own-agent.mdx Normal file
View File

@@ -0,0 +1,441 @@
---
title: Traga seu próprio agente
description: Aprenda como trazer seus próprios agentes que funcionam dentro de uma Crew.
icon: robots
---
Interoperabilidade é um conceito fundamental no CrewAI. Este guia mostrará como trazer seus próprios agentes para funcionar dentro de uma Crew.
## Guia de Adaptação para trazer seus próprios agentes (Agentes Langgraph, Agentes OpenAI, etc...)
Requeremos 3 adaptadores para tornar qualquer agente de diferentes frameworks compatível com uma crew.
1. BaseAgentAdapter
2. BaseToolAdapter
3. BaseConverter
## BaseAgentAdapter
Esta classe abstrata define a interface comum e a funcionalidade que todos
os adaptadores de agente devem implementar. Ela estende BaseAgent para manter compatibilidade
com o framework CrewAI, ao mesmo tempo em que adiciona requisitos específicos do adaptador.
Métodos obrigatórios:
1. `def configure_tools`
2. `def configure_structured_output`
## Criando seu próprio Adaptador
Para integrar um agente de um framework diferente (por exemplo, LangGraph, Autogen, OpenAI Assistants) ao CrewAI, você precisa criar um adaptador customizado herdando de `BaseAgentAdapter`. Esse adaptador atua como uma camada de compatibilidade, traduzindo entre as interfaces do CrewAI e os requisitos específicos do seu agente externo.
Veja como implementar seu adaptador customizado:
1. **Herdar de `BaseAgentAdapter`**:
```python
from crewai.agents.agent_adapters.base_agent_adapter import BaseAgentAdapter
from crewai.tools import BaseTool
from typing import List, Optional, Any, Dict
class MyCustomAgentAdapter(BaseAgentAdapter):
# ... detalhes da implementação ...
```
2. **Implementar `__init__`**:
O construtor deve chamar o construtor da classe pai `super().__init__(**kwargs)` e executar qualquer inicialização específica do seu agente externo. Você pode usar o dicionário opcional `agent_config` passado durante a inicialização do `Agent` do CrewAI para configurar seu adaptador e o agente subjacente.
```python
def __init__(self, agent_config: Optional[Dict[str, Any]] = None, **kwargs: Any):
super().__init__(agent_config=agent_config, **kwargs)
# Inicialize seu agente externo aqui, possivelmente usando agent_config
# Exemplo: self.external_agent = initialize_my_agent(agent_config)
print(f"Inicializando MyCustomAgentAdapter com config: {agent_config}")
```
3. **Implementar `configure_tools`**:
Este método abstrato é crucial. Ele recebe uma lista de instâncias de `BaseTool` do CrewAI. Sua implementação deve converter ou adaptar essas ferramentas para o formato esperado pelo seu framework de agente externo. Isso pode envolver encapsulamento, extração de atributos específicos ou registro delas na instância do agente externo.
```python
def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None:
if tools:
adapted_tools = []
for tool in tools:
# Adapte o CrewAI BaseTool para o formato que seu agente espera
# Exemplo: adapted_tool = adapt_to_my_framework(tool)
# adapted_tools.append(adapted_tool)
pass # Substitua pela sua lógica real de adaptação
# Configure o agente externo com as ferramentas adaptadas
# Exemplo: self.external_agent.set_tools(adapted_tools)
print(f"Configurando ferramentas para MyCustomAgentAdapter: {adapted_tools}") # Placeholder
else:
# Caso nenhum ferramenta seja fornecida
# Exemplo: self.external_agent.set_tools([])
print("Nenhuma ferramenta fornecida para MyCustomAgentAdapter.")
```
4. **Implementar `configure_structured_output`**:
Esse método é chamado quando o `Agent` do CrewAI é configurado com requisitos de saída estruturada (por exemplo, `output_json` ou `output_pydantic`). Seu adaptador precisa garantir que o agente externo esteja configurado para cumprir esses requisitos. Isso pode envolver definir parâmetros específicos no agente externo ou garantir que seu modelo subjacente suporte o formato solicitado. Se o agente externo não suportar saída estruturada de forma compatível com as expectativas do CrewAI, talvez seja necessário lidar com a conversão ou lançar um erro apropriado.
```python
def configure_structured_output(self, structured_output: Any) -> None:
# Configure seu agente externo para produzir saída no formato especificado
# Exemplo: self.external_agent.set_output_format(structured_output)
self.adapted_structured_output = True # Sinaliza que a saída estruturada foi tratada
print(f"Configurando saída estruturada para MyCustomAgentAdapter: {structured_output}")
```
Implementando esses métodos, seu `MyCustomAgentAdapter` permitirá que sua implementação personalizada de agente funcione corretamente dentro de uma crew do CrewAI, interagindo com tarefas e ferramentas de forma transparente. Lembre-se de substituir os comentários e prints de exemplo pela sua lógica real de adaptação específica do framework externo que está integrando.
## Implementação de BaseToolAdapter
A classe `BaseToolAdapter` é responsável por converter os objetos nativos `BaseTool` do CrewAI em um formato que o seu framework de agente externo possa entender e utilizar. Diferentes frameworks de agentes (como LangGraph, OpenAI Assistants, etc.) possuem suas próprias formas de definir e tratar ferramentas, e o `BaseToolAdapter` age como tradutor.
Veja como implementar seu adaptador de ferramentas personalizado:
1. **Herdar de `BaseToolAdapter`**:
```python
from crewai.agents.agent_adapters.base_tool_adapter import BaseToolAdapter
from crewai.tools import BaseTool
from typing import List, Any
class MyCustomToolAdapter(BaseToolAdapter):
# ... detalhes da implementação ...
```
2. **Implementar `configure_tools`**:
Este é o método abstrato principal que você deve implementar. Ele recebe uma lista de instâncias de `BaseTool` fornecidas ao agente. Sua tarefa é iterar por essa lista, adaptar cada `BaseTool` para o formato esperado pelo seu framework externo e armazenar as ferramentas convertidas na lista `self.converted_tools` (inicializada no construtor da classe base).
```python
def configure_tools(self, tools: List[BaseTool]) -> None:
"""Configura e converte ferramentas do CrewAI para a implementação específica."""
self.converted_tools = [] # Reseta caso seja chamado múltiplas vezes
for tool in tools:
# Sanitizar o nome da ferramenta se necessário pelo framework alvo
sanitized_name = self.sanitize_tool_name(tool.name)
# --- Sua lógica de conversão aqui ---
# Exemplo: Converter BaseTool para formato de dicionário para LangGraph
# converted_tool = {
# "name": sanitized_name,
# "description": tool.description,
# "parameters": tool.args_schema.schema() if tool.args_schema else {},
# # Adicione outros campos específicos do framework
# }
# Exemplo: Converter BaseTool para definição de função OpenAI
# converted_tool = {
# "type": "function",
# "function": {
# "name": sanitized_name,
# "description": tool.description,
# "parameters": tool.args_schema.schema() if tool.args_schema else {"type": "object", "properties": {}},
# }
# }
# --- Substitua os exemplos acima pela sua adaptação real ---
converted_tool = self.adapt_tool_to_my_framework(tool, sanitized_name) # Placeholder
self.converted_tools.append(converted_tool)
print(f"Ferramenta '{tool.name}' adaptada para '{sanitized_name}' em MyCustomToolAdapter") # Placeholder
print(f"MyCustomToolAdapter terminou de configurar ferramentas: {len(self.converted_tools)} adaptadas.") # Placeholder
# --- Método auxiliar para adaptação (Exemplo) ---
def adapt_tool_to_my_framework(self, tool: BaseTool, sanitized_name: str) -> Any:
# Substitua pela lógica real para converter um CrewAI BaseTool
# para o formato necessário do framework de agente externo específico.
# Isso pode variar bastante de acordo com o framework.
adapted_representation = {
"framework_specific_name": sanitized_name,
"framework_specific_description": tool.description,
"inputs": tool.args_schema.schema() if tool.args_schema else None,
"implementation_reference": tool.run # Ou conforme o framework precisa chamar
}
# Certifique-se também que a ferramenta funcione tanto síncrona quanto assincronamente
async def async_tool_wrapper(*args, **kwargs):
output = tool.run(*args, **kwargs)
if inspect.isawaitable(output):
return await output
else:
return output
adapted_tool = MyFrameworkTool(
name=sanitized_name,
description=tool.description,
inputs=tool.args_schema.schema() if tool.args_schema else None,
implementation_reference=async_tool_wrapper
)
return adapted_representation
```
3. **Utilizando o Adaptador**:
Normalmente, você instanciaria seu `MyCustomToolAdapter` dentro do método `configure_tools` do seu `MyCustomAgentAdapter` e o usaria para processar as ferramentas antes de configurar o agente externo.
```python
# Dentro de MyCustomAgentAdapter.configure_tools
def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None:
if tools:
tool_adapter = MyCustomToolAdapter() # Instancia seu adaptador de ferramenta
tool_adapter.configure_tools(tools) # Converte as ferramentas
adapted_tools = tool_adapter.tools() # Obtém as ferramentas convertidas
# Agora configure seu agente externo com as ferramentas adaptadas
# Exemplo: self.external_agent.set_tools(adapted_tools)
print(f"Configurando agente externo com ferramentas adaptadas: {adapted_tools}") # Placeholder
else:
# Caso sem ferramentas
print("Nenhuma ferramenta fornecida para MyCustomAgentAdapter.")
```
Ao criar um `BaseToolAdapter`, você desacopla a lógica de conversão de ferramenta da adaptação de agente, tornando a integração mais limpa e modular. Lembre-se de substituir os exemplos de placeholder pela lógica de conversão real exigida pelo seu framework externo específico.
## BaseConverter
O `BaseConverterAdapter` desempenha um papel crucial quando uma `Task` do CrewAI exige que um agente retorne sua saída final em um formato estruturado específico, como JSON ou um modelo Pydantic. Ele faz a ponte entre os requisitos de saída estruturada do CrewAI e as capacidades do seu agente externo.
Suas responsabilidades principais são:
1. **Configurar o Agente para Saída Estruturada:** Com base nos requisitos da `Task` (`output_json` ou `output_pydantic`), ele instrui o `BaseAgentAdapter` associado (e indiretamente, o agente externo) sobre qual formato é esperado.
2. **Apriorar o Prompt do Sistema:** Ele modifica o prompt do sistema do agente para incluir instruções claras sobre *como* gerar a saída na estrutura exigida.
3. **Pós-processamento do Resultado:** Pega a saída bruta do agente e tenta fazer parsing, validar e formatar conforme a estrutura requerida, retornando por fim uma representação em string (por exemplo, uma string JSON).
Veja como implementar seu adaptador de conversão customizado:
1. **Herdar de `BaseConverterAdapter`**:
```python
from crewai.agents.agent_adapters.base_converter_adapter import BaseConverterAdapter
# Supondo que o seu MyCustomAgentAdapter foi definido
# from .my_custom_agent_adapter import MyCustomAgentAdapter
from crewai.task import Task
from typing import Any
class MyCustomConverterAdapter(BaseConverterAdapter):
# Armazena o tipo de saída esperado (ex: 'json', 'pydantic', 'text')
_output_type: str = 'text'
_output_schema: Any = None # Armazena o schema JSON ou modelo Pydantic
# ... detalhes da implementação ...
```
2. **Implementar `__init__`**:
O construtor deve aceitar a instância correspondente de `agent_adapter` com a qual irá trabalhar.
```python
def __init__(self, agent_adapter: Any): # Use um type hint específico para seu AgentAdapter
self.agent_adapter = agent_adapter
print(f"Inicializando MyCustomConverterAdapter para o adaptador de agente: {type(agent_adapter).__name__}")
```
3. **Implementar `configure_structured_output`**:
Esse método recebe o objeto `Task` do CrewAI. Você precisa checar os atributos `output_json` e `output_pydantic` da task para determinar a estrutura de saída exigida. Armazene essa informação (por exemplo, em `_output_type` e `_output_schema`) e, potencialmente, chame métodos de configuração no seu `self.agent_adapter` se o agente externo necessitar de um ajuste específico para saída estruturada (algo que pode já ter sido parcialmente feito no `configure_structured_output` do adaptador de agente).
```python
def configure_structured_output(self, task: Task) -> None:
"""Configura a saída estruturada esperada baseada na task."""
if task.output_pydantic:
self._output_type = 'pydantic'
self._output_schema = task.output_pydantic
print(f"Converter: Configurado para saída Pydantic: {self._output_schema.__name__}")
elif task.output_json:
self._output_type = 'json'
self._output_schema = task.output_json
print(f"Converter: Configurado para saída JSON com schema: {self._output_schema}")
else:
self._output_type = 'text'
self._output_schema = None
print("Converter: Configurado para saída de texto padrão.")
# Opcionalmente, informe o agent_adapter se necessário
# self.agent_adapter.set_output_mode(self._output_type, self._output_schema)
```
4. **Implementar `enhance_system_prompt`**:
Este método recebe o prompt base do sistema do agente e deve anexar instruções adaptadas para o `_output_type` e `_output_schema` atualmente configurados. O objetivo é guiar o LLM que alimenta o agente a produzir saída no formato correto.
```python
def enhance_system_prompt(self, base_prompt: str) -> str:
"""Aprimore o prompt do sistema com instruções de saída estruturada."""
if self._output_type == 'text':
return base_prompt # Nenhum aprimoramento necessário para texto puro
instructions = "\n\nSua resposta final DEVE estar formatada como "
if self._output_type == 'json':
schema_str = json.dumps(self._output_schema, indent=2)
instructions += f"um objeto JSON conforme o seguinte schema:\n```json\n{schema_str}\n```"
elif self._output_type == 'pydantic':
schema_str = json.dumps(self._output_schema.model_json_schema(), indent=2)
instructions += f"um objeto JSON conforme o modelo Pydantic '{self._output_schema.__name__}' com o seguinte schema:\n```json\n{schema_str}\n```"
instructions += "\nGaranta que toda a sua resposta seja APENAS o objeto JSON válido, sem nenhum texto introdutório, explicações ou considerações finais."
print(f"Converter: Aprimorando prompt para saída {self._output_type}.")
return base_prompt + instructions
```
*Nota: O prompt pode precisar de ajustes conforme o agente/LLM usado.*
5. **Implementar `post_process_result`**:
Esse método recebe a saída em string bruta do agente. Se uma saída estruturada foi solicitada (`json` ou `pydantic`), você deve tentar convertê-la para o formato esperado. Trate erros de parsing caso ocorram (por exemplo, registre-os, tente corrigir, ou lance uma exceção). O método **deve sempre retornar uma string**, mesmo se o formato intermediário seja um dicionário ou objeto Pydantic (por exemplo, serializando novamente para JSON).
```python
import json
from pydantic import ValidationError
def post_process_result(self, result: str) -> str:
"""Pós-processa o resultado do agente para garantir que corresponde ao formato esperado."""
print(f"Converter: Pós-processando resultado para saída {self._output_type}.")
if self._output_type == 'json':
try:
# Tenta fazer parsing e re-serializar para garantir validade e formato consistente
parsed_json = json.loads(result)
# Opcional: Validar contra o schema se for um dicionário JSON schema
# from jsonschema import validate
# validate(instance=parsed_json, schema=self._output_schema)
return json.dumps(parsed_json)
except json.JSONDecodeError as e:
print(f"Erro: Falha ao fazer parsing da saída JSON: {e}\nSaída bruta:\n{result}")
# Trate o erro: retorne bruto, lance exceção, ou tente corrigir
return result # Exemplo: retorna a saída bruta caso falhe
# except Exception as e: # Captura erros de validação se usar jsonschema
# print(f"Erro: saída JSON falhou na validação do schema: {e}\nSaída bruta:\n{result}")
# return result
elif self._output_type == 'pydantic':
try:
# Tenta fazer parsing para o modelo Pydantic
model_instance = self._output_schema.model_validate_json(result)
# Retorna o modelo serializado de volta para JSON
return model_instance.model_dump_json()
except ValidationError as e:
print(f"Erro: Falha ao validar saída Pydantic: {e}\nSaída bruta:\n{result}")
# Trate o erro
return result # Exemplo: retorna a saída bruta caso falhe
except json.JSONDecodeError as e:
print(f"Erro: Falha ao fazer parsing do JSON para o modelo Pydantic: {e}\nSaída bruta:\n{result}")
return result
else: # 'text'
return result # Sem processamento para texto puro
```
Implementando esses métodos, seu `MyCustomConverterAdapter` assegurará que as solicitações de saída estruturada das tarefas do CrewAI sejam corretamente tratadas pelo seu agente externo integrado, aumentando a confiabilidade e a usabilidade do seu agente customizado dentro do framework CrewAI.
## Adapters prontos para uso
Fornecemos adapters prontos para uso para os seguintes frameworks:
1. LangGraph
2. Agentes OpenAI
## Iniciando uma crew com agentes adaptados:
```python
import json
import os
from typing import List
from crewai_tools import SerperDevTool
from src.crewai import Agent, Crew, Task
from langchain_openai import ChatOpenAI
from pydantic import BaseModel
from crewai.agents.agent_adapters.langgraph.langgraph_adapter import (
LangGraphAgentAdapter,
)
from crewai.agents.agent_adapters.openai_agents.openai_adapter import OpenAIAgentAdapter
# Agente CrewAI
code_helper_agent = Agent(
role="Code Helper",
goal="Help users solve coding problems effectively and provide clear explanations.",
backstory="You are an experienced programmer with deep knowledge across multiple programming languages and frameworks. You specialize in solving complex coding challenges and explaining solutions clearly.",
allow_delegation=False,
verbose=True,
)
# OpenAI Agent Adapter
link_finder_agent = OpenAIAgentAdapter(
role="Link Finder",
goal="Find the most relevant and high-quality resources for coding tasks.",
backstory="You are a research specialist with a talent for finding the most helpful resources. You're skilled at using search tools to discover documentation, tutorials, and examples that directly address the user's coding needs.",
tools=[SerperDevTool()],
allow_delegation=False,
verbose=True,
)
# LangGraph Agent Adapter
reporter_agent = LangGraphAgentAdapter(
role="Reporter",
goal="Report the results of the tasks.",
backstory="You are a reporter who reports the results of the other tasks",
llm=ChatOpenAI(model="gpt-4o"),
allow_delegation=True,
verbose=True,
)
class Code(BaseModel):
code: str
task = Task(
description="Give an answer to the coding question: {task}",
expected_output="A thorough answer to the coding question: {task}",
agent=code_helper_agent,
output_json=Code,
)
task2 = Task(
description="Find links to resources that can help with coding tasks. Use the serper tool to find resources that can help.",
expected_output="A list of links to resources that can help with coding tasks",
agent=link_finder_agent,
)
class Report(BaseModel):
code: str
links: List[str]
task3 = Task(
description="Report the results of the tasks.",
expected_output="A report of the results of the tasks. this is the code produced and then the links to the resources that can help with the coding task.",
agent=reporter_agent,
output_json=Report,
)
# Usando no CrewAI
crew = Crew(
agents=[code_helper_agent, link_finder_agent, reporter_agent],
tasks=[task, task2, task3],
verbose=True,
)
result = crew.kickoff(
inputs={"task": "How do you implement an abstract class in python?"}
)
# Imprima o resultado bruto primeiro
print("Raw result:", result)
# Lide com o resultado de acordo com seu tipo
if hasattr(result, "json_dict") and result.json_dict:
json_result = result.json_dict
print("\nStructured JSON result:")
print(f"{json.dumps(json_result, indent=2)}")
# Acesse os campos de forma segura
if isinstance(json_result, dict):
if "code" in json_result:
print("\nCode:")
print(
json_result["code"][:200] + "..."
if len(json_result["code"]) > 200
else json_result["code"]
)
if "links" in json_result:
print("\nLinks:")
for link in json_result["links"][:5]: # Print first 5 links
print(f"- {link}")
if len(json_result["links"]) > 5:
print(f"...and {len(json_result['links']) - 5} more links")
elif hasattr(result, "pydantic") and result.pydantic:
print("\nPydantic model result:")
print(result.pydantic.model_dump_json(indent=2))
else:
# Fallback para saída bruta
print("\nNo structured result available, using raw output:")
print(result.raw[:500] + "..." if len(result.raw) > 500 else result.raw)
```

95
docs/pt-BR/learn/coding-agents.mdx Normal file
View File

@@ -0,0 +1,95 @@
---
title: Agentes de Codificação
description: Aprenda como habilitar seus Agentes CrewAI para escrever e executar código, e explore funcionalidades avançadas para maior potencial.
icon: rectangle-code
---
## Introdução
Os Agentes CrewAI agora têm a poderosa capacidade de escrever e executar código, aumentando significativamente suas habilidades de resolução de problemas. Esse recurso é particularmente útil para tarefas que exigem soluções computacionais ou programáticas.
## Habilitando a Execução de Código
Para habilitar a execução de código para um agente, defina o parâmetro `allow_code_execution` como `True` ao criar o agente.
Veja um exemplo:
```python Code
from crewai import Agent
coding_agent = Agent(
role="Senior Python Developer",
goal="Craft well-designed and thought-out code",
backstory="You are a senior Python developer with extensive experience in software architecture and best practices.",
allow_code_execution=True
)
```
<Note>
Observe que o parâmetro `allow_code_execution` é `False` por padrão.
</Note>
## Considerações Importantes
1. **Seleção de Modelo**: É fortemente recomendado utilizar modelos mais avançados como Claude 3.5 Sonnet e GPT-4 ao habilitar a execução de código.
Esses modelos têm melhor compreensão de conceitos de programação e tendem a gerar códigos mais corretos e eficientes.
2. **Tratamento de Erros**: O recurso de execução de código inclui tratamento de erros. Se o código executado gerar uma exceção, o agente receberá a mensagem de erro e poderá tentar corrigir o código ou
fornecer soluções alternativas. O parâmetro `max_retry_limit`, que por padrão é 2, controla o número máximo de tentativas para uma tarefa.
3. **Dependências**: Para usar o recurso de execução de código, é necessário instalar o pacote `crewai_tools`. Caso não esteja instalado, o agente registrará uma mensagem informativa:
"Ferramentas de codificação não disponíveis. Instale crewai_tools."
## Processo de Execução de Código
Quando um agente com execução de código habilitada encontra uma tarefa que requer programação:
<Steps>
<Step title="Análise da Tarefa">
O agente analisa a tarefa e determina que a execução de código é necessária.
</Step>
<Step title="Formulação do Código">
Ele formula o código Python necessário para resolver o problema.
</Step>
<Step title="Execução do Código">
O código é enviado para a ferramenta interna de execução de código (`CodeInterpreterTool`).
</Step>
<Step title="Interpretação dos Resultados">
O agente interpreta o resultado e o incorpora na sua resposta ou o utiliza para aprofundar a solução do problema.
</Step>
</Steps>
## Exemplo de Uso
Veja um exemplo detalhado de como criar um agente com capacidade de execução de código e utilizá-lo em uma tarefa:
```python Code
from crewai import Agent, Task, Crew
# Create an agent with code execution enabled
coding_agent = Agent(
role="Python Data Analyst",
goal="Analyze data and provide insights using Python",
backstory="You are an experienced data analyst with strong Python skills.",
allow_code_execution=True
)
# Create a task that requires code execution
data_analysis_task = Task(
description="Analyze the given dataset and calculate the average age of participants.",
agent=coding_agent
)
# Create a crew and add the task
analysis_crew = Crew(
agents=[coding_agent],
tasks=[data_analysis_task]
)
# Execute the crew
result = analysis_crew.kickoff()
print(result)
```
Neste exemplo, o `coding_agent` pode escrever e executar código Python para realizar tarefas de análise de dados.

89
docs/pt-BR/learn/conditional-tasks.mdx Normal file
View File

@@ -0,0 +1,89 @@
---
title: Tarefas Condicionais
description: Saiba como usar tarefas condicionais em um kickoff do crewAI
icon: diagram-subtask
---
## Introdução
As Tarefas Condicionais no crewAI permitem a adaptação dinâmica do fluxo de trabalho com base nos resultados de tarefas anteriores.
Esse recurso poderoso possibilita que crews tomem decisões e executem tarefas seletivamente, aumentando a flexibilidade e a eficiência dos seus processos orientados por IA.
## Exemplo de Uso
```python Code
from typing import List
from pydantic import BaseModel
from crewai import Agent, Crew
from crewai.tasks.conditional_task import ConditionalTask
from crewai.tasks.task_output import TaskOutput
from crewai.task import Task
from crewai_tools import SerperDevTool
# Define a condition function for the conditional task
# If false, the task will be skipped, if true, then execute the task.
def is_data_missing(output: TaskOutput) -> bool:
return len(output.pydantic.events) < 10 # this will skip this task
# Define the agents
data_fetcher_agent = Agent(
role="Data Fetcher",
goal="Fetch data online using Serper tool",
backstory="Backstory 1",
verbose=True,
tools=[SerperDevTool()]
)
data_processor_agent = Agent(
role="Data Processor",
goal="Process fetched data",
backstory="Backstory 2",
verbose=True
)
summary_generator_agent = Agent(
role="Summary Generator",
goal="Generate summary from fetched data",
backstory="Backstory 3",
verbose=True
)
class EventOutput(BaseModel):
events: List[str]
task1 = Task(
description="Fetch data about events in San Francisco using Serper tool",
expected_output="List of 10 things to do in SF this week",
agent=data_fetcher_agent,
output_pydantic=EventOutput,
)
conditional_task = ConditionalTask(
description="""
Check if data is missing. If we have less than 10 events,
fetch more events using Serper tool so that
we have a total of 10 events in SF this week..
""",
expected_output="List of 10 Things to do in SF this week",
condition=is_data_missing,
agent=data_processor_agent,
)
task3 = Task(
description="Generate summary of events in San Francisco from fetched data",
expected_output="A complete report on the customer and their customers and competitors, including their demographics, preferences, market positioning and audience engagement.",
agent=summary_generator_agent,
)
# Create a crew with the tasks
crew = Crew(
agents=[data_fetcher_agent, data_processor_agent, summary_generator_agent],
tasks=[task1, conditional_task, task3],
verbose=True,
planning=True
)
# Run the crew
result = crew.kickoff()
print("results", result)
```

69
docs/pt-BR/learn/create-custom-tools.mdx Normal file
View File

@@ -0,0 +1,69 @@
---
title: Criar Ferramentas Personalizadas
description: Guia abrangente sobre como criar, utilizar e gerenciar ferramentas personalizadas dentro do framework CrewAI, incluindo novas funcionalidades e tratamento de erros.
icon: hammer
---
## Criando e Utilizando Ferramentas no CrewAI
Este guia traz instruções detalhadas sobre como criar ferramentas personalizadas para o framework CrewAI e como gerenciar e utilizar essas ferramentas de forma eficiente,
incorporando funcionalidades recentes, como delegação de ferramentas, tratamento de erros e chamada dinâmica de ferramentas. Destaca também a importância de ferramentas de colaboração,
permitindo que agentes executem uma ampla gama de ações.
### Subclassificando `BaseTool`
Para criar uma ferramenta personalizada, herde de `BaseTool` e defina os atributos necessários, incluindo o `args_schema` para validação de entrada e o método `_run`.
```python Code
from typing import Type
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:
# Your tool's logic here
return "Tool's result"
```
### Usando o Decorador `tool`
Como alternativa, você pode utilizar o decorador de ferramenta `@tool`. Esta abordagem permite definir os atributos e as funcionalidades da ferramenta diretamente em uma função,
oferecendo uma maneira concisa e eficiente de criar ferramentas especializadas de acordo com suas necessidades.
```python Code
from crewai.tools import tool
@tool("Tool Name")
def my_simple_tool(question: str) -> str:
"""Tool description for clarity."""
# Tool logic here
return "Tool output"
```
### Definindo uma Função de Cache para a Ferramenta
Para otimizar o desempenho da ferramenta com cache, defina estratégias de cache personalizadas utilizando o atributo `cache_function`.
```python Code
@tool("Tool with Caching")
def cached_tool(argument: str) -> str:
"""Tool functionality description."""
return "Cacheable result"
def my_cache_strategy(arguments: dict, result: str) -> bool:
# Define custom caching logic
return True if some_condition else False
cached_tool.cache_function = my_cache_strategy
```
Seguindo essas orientações e incorporando novas funcionalidades e ferramentas de colaboração nos seus processos de criação e gerenciamento de ferramentas,
você pode aproveitar ao máximo as capacidades do framework CrewAI, aprimorando tanto a experiência de desenvolvimento quanto a eficiência dos seus agentes de IA.

122
docs/pt-BR/learn/custom-llm.mdx Normal file
View File

@@ -0,0 +1,122 @@
---
title: Implementação de LLM Personalizada
description: Aprenda a criar implementações personalizadas de LLM no CrewAI.
icon: code
---
## Visão Geral
O CrewAI oferece suporte a implementações personalizadas de LLM por meio da classe abstrata `BaseLLM`. Isso permite integrar qualquer provedor de LLM que não tenha suporte nativo no LiteLLM ou implementar mecanismos de autenticação personalizados.
## Início Rápido
Aqui está uma implementação mínima de LLM personalizada:
```python
# (não traduzir blocos de código)
```
## Usando Seu LLM Personalizado
```python
# (não traduzir blocos de código)
```
## Métodos Necessários
### Construtor: `__init__()`
**Crítico**: Você deve chamar `super().__init__(model, temperature)` com os parâmetros necessários:
```python
# (não traduzir blocos de código)
```
### Método Abstrato: `call()`
O método `call()` é o núcleo da sua implementação de LLM. Ele deve:
- Aceitar mensagens (string ou lista de dicionários com 'role' e 'content')
- Retornar uma resposta como string
- Lidar com ferramentas e chamada de funções, se suportado
- Lançar exceções apropriadas para erros
### Métodos Opcionais
```python
# (não traduzir blocos de código)
```
## Padrões Comuns
### Tratamento de Erros
```python
# (não traduzir blocos de código)
```
### Autenticação Personalizada
```python
# (não traduzir blocos de código)
```
### Suporte a Stop Words
O CrewAI adiciona automaticamente `"\nObservation:"` como stop word para controlar o comportamento do agente. Se o seu LLM suporta stop words:
```python
# (não traduzir blocos de código)
```
Se o seu LLM não suporta stop words nativamente:
```python
# (não traduzir blocos de código)
```
## Chamada de Funções
Se o seu LLM suporta chamada de funções, implemente o fluxo completo:
```python
# (não traduzir blocos de código)
```
## Solução de Problemas
### Problemas Comuns
**Erros no Construtor**
```python
# ❌ Errado - parâmetros obrigatórios ausentes
def __init__(self, api_key: str):
super().__init__()
# ✅ Correto
def __init__(self, model: str, api_key: str, temperature: Optional[float] = None):
super().__init__(model=model, temperature=temperature)
```
**Chamada de Funções Não Funciona**
- Certifique-se de que `supports_function_calling()` retorna `True`
- Verifique se você lida com `tool_calls` na resposta
- Assegure-se de que o parâmetro `available_functions` está sendo corretamente utilizado
**Falhas de Autenticação**
- Verifique o formato e as permissões da chave de API
- Confira o formato do header de autenticação
- Certifique-se de que as URLs dos endpoints estão corretas
**Erros de Parsing de Resposta**
- Valide a estrutura da resposta antes de acessar campos aninhados
- Trate casos em que o content pode ser None
- Adicione tratamento de erros para respostas malformadas
## Testando Seu LLM Personalizado
```python
# (não traduzir blocos de código)
```
Este guia cobre o essencial para implementar LLMs personalizados no CrewAI.

90
docs/pt-BR/learn/custom-manager-agent.mdx Normal file
View File

@@ -0,0 +1,90 @@
---
title: Agente Gerente Personalizado
description: Saiba como definir um agente personalizado como gerente no CrewAI, proporcionando mais controle sobre o gerenciamento e a coordenação das tarefas.
icon: user-shield
---
# Definindo um Agente Específico como Gerente no CrewAI
O CrewAI permite que usuários definam um agente específico como gerente da crew, oferecendo mais controle sobre o gerenciamento e a coordenação das tarefas.
Esse recurso possibilita a personalização do papel gerencial para se adequar melhor às necessidades do seu projeto.
## Utilizando o Atributo `manager_agent`
### Agente Gerente Personalizado
O atributo `manager_agent` permite que você defina um agente personalizado para gerenciar a crew. Este agente supervisionará todo o processo, garantindo que as tarefas sejam concluídas de forma eficiente e com o mais alto padrão de qualidade.
### Exemplo
```python Code
import os
from crewai import Agent, Task, Crew, Process
# Define your agents
researcher = Agent(
role="Researcher",
goal="Conduct thorough research and analysis on AI and AI agents",
backstory="You're an expert researcher, specialized in technology, software engineering, AI, and startups. You work as a freelancer and are currently researching for a new client.",
allow_delegation=False,
)
writer = Agent(
role="Senior Writer",
goal="Create compelling content about AI and AI agents",
backstory="You're a senior writer, specialized in technology, software engineering, AI, and startups. You work as a freelancer and are currently writing content for a new client.",
allow_delegation=False,
)
# Define your task
task = Task(
description="Generate a list of 5 interesting ideas for an article, then write one captivating paragraph for each idea that showcases the potential of a full article on this topic. Return the list of ideas with their paragraphs and your notes.",
expected_output="5 bullet points, each with a paragraph and accompanying notes.",
)
# Define the manager agent
manager = Agent(
role="Project Manager",
goal="Efficiently manage the crew and ensure high-quality task completion",
backstory="You're an experienced project manager, skilled in overseeing complex projects and guiding teams to success. Your role is to coordinate the efforts of the crew members, ensuring that each task is completed on time and to the highest standard.",
allow_delegation=True,
)
# Instantiate your crew with a custom manager
crew = Crew(
agents=[researcher, writer],
tasks=[task],
manager_agent=manager,
process=Process.hierarchical,
)
# Start the crew's work
result = crew.kickoff()
```
## Benefícios de um Agente Gerente Personalizado
- **Controle aprimorado**: Adapte a abordagem de gerenciamento para atender às necessidades específicas do seu projeto.
- **Coordenação melhorada**: Assegure uma coordenação e gestão eficiente das tarefas por um agente experiente.
- **Gestão personalizável**: Defina funções e responsabilidades gerenciais que estejam alinhadas aos objetivos do seu projeto.
## Definindo um Manager LLM
Se você estiver utilizando o processo hierarchical e não quiser definir um agente gerente personalizado, é possível especificar o modelo de linguagem para o gerente:
```python Code
from crewai import LLM
manager_llm = LLM(model="gpt-4o")
crew = Crew(
agents=[researcher, writer],
tasks=[task],
process=Process.hierarchical,
manager_llm=manager_llm
)
```
<Note>
É necessário definir `manager_agent` ou `manager_llm` ao utilizar o processo hierarchical.
</Note>

111
docs/pt-BR/learn/customizing-agents.mdx Normal file
View File

@@ -0,0 +1,111 @@
---
title: Personalize Agentes
description: Um guia abrangente para adaptar agentes a funções específicas, tarefas e customizações avançadas dentro do framework CrewAI.
icon: user-pen
---
## Atributos Personalizáveis
A construção de uma equipe CrewAI eficiente depende da capacidade de adaptar dinamicamente seus agentes de IA para atender aos requisitos únicos de qualquer projeto. Esta seção aborda os atributos fundamentais que você pode personalizar.
### Principais Atributos para Personalização
| Atributo | Descrição |
|:------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Role** | Especifica a função do agente dentro da equipe, como 'Analista' ou 'Representante de Atendimento ao Cliente'. |
| **Goal** | Define os objetivos do agente, alinhados à sua função e à missão geral da equipe. |
| **Backstory** | Fornece profundidade à persona do agente, aprimorando motivações e engajamento dentro da equipe. |
| **Tools** *(Opcional)* | Representa as capacidades ou métodos que o agente utiliza para tarefas, desde funções simples até integrações complexas. |
| **Cache** *(Opcional)* | Determina se o agente deve usar cache para o uso de ferramentas. |
| **Max RPM** | Define o número máximo de requisições por minuto (`max_rpm`). Pode ser definido como `None` para requisições ilimitadas a serviços externos. |
| **Verbose** *(Opcional)* | Ativa registros detalhados para depuração e otimização, fornecendo insights sobre os processos de execução. |
| **Allow Delegation** *(Opcional)* | Controla a delegação de tarefas para outros agentes, padrão é `False`. |
| **Max Iter** *(Opcional)* | Limita o número máximo de iterações (`max_iter`) para uma tarefa, prevenindo loops infinitos, com valor padrão de 25. |
| **Max Execution Time** *(Opcional)* | Define o tempo máximo permitido para que o agente complete uma tarefa. |
| **System Template** *(Opcional)* | Define o formato do sistema para o agente. |
| **Prompt Template** *(Opcional)* | Define o formato do prompt para o agente. |
| **Response Template** *(Opcional)* | Define o formato da resposta para o agente. |
| **Use System Prompt** *(Opcional)* | Controla se o agente irá usar um prompt de sistema durante a execução de tarefas. |
| **Respect Context Window** | Ativa uma janela deslizante de contexto por padrão, mantendo o tamanho do contexto. |
| **Max Retry Limit** | Define o número máximo de tentativas (`max_retry_limit`) para um agente em caso de erros. |
## Opções Avançadas de Personalização
Além dos atributos básicos, o CrewAI permite customizações mais profundas para aprimorar significativamente o comportamento e as capacidades de um agente.
### Personalização de Modelo de Linguagem
Agentes podem ser personalizados com modelos de linguagem específicos (`llm`) e modelos de linguagem com chamada de função (`function_calling_llm`), oferecendo controle avançado sobre o processamento e a tomada de decisão.
É importante notar que definir o `function_calling_llm` permite sobrescrever o modelo padrão de chamada de função da equipe, proporcionando maior grau de personalização.
## Ajustes de Performance e Depuração
Ajustar a performance do agente e monitorar suas operações é fundamental para a execução eficiente de tarefas.
### Modo Verbose e Limite de RPM
- **Modo Verbose**: Ativa o registro detalhado das ações do agente, útil para depuração e otimização. Especificamente, fornece insights sobre os processos de execução do agente, auxiliando na otimização de performance.
- **Limite de RPM**: Define o número máximo de requisições por minuto (`max_rpm`). Este atributo é opcional e pode ser definido como `None` para não haver limite, permitindo consultas ilimitadas a serviços externos, se necessário.
### Máximo de Iterações por Execução de Tarefa
O atributo `max_iter` permite ao usuário definir o número máximo de iterações que um agente pode executar para uma única tarefa, prevenindo loops infinitos ou execuções excessivamente longas.
O valor padrão é 25, fornecendo um equilíbrio entre profundidade e eficiência. Quando o agente chega próximo a esse número, ele tentará entregar a melhor resposta possível.
## Personalizando Agentes e Ferramentas
Agentes são personalizados definindo seus atributos e ferramentas durante a inicialização. As ferramentas são críticas para a funcionalidade do agente, permitindo que realizem tarefas especializadas.
O atributo `tools` deve ser um array de ferramentas que o agente pode utilizar, e, por padrão, é inicializado como uma lista vazia. As ferramentas podem ser adicionadas ou modificadas após a criação do agente para se adaptar a novos requisitos.
```shell
pip install 'crewai[tools]'
```
### Exemplo: Atribuindo Ferramentas a um Agente
```python Code
import os
from crewai import Agent
from crewai_tools import SerperDevTool
# Defina as chaves de API para inicialização da ferramenta
os.environ["OPENAI_API_KEY"] = "Sua Chave"
os.environ["SERPER_API_KEY"] = "Sua Chave"
# Inicialize uma ferramenta de busca
search_tool = SerperDevTool()
# Inicialize o agente com opções avançadas
agent = Agent(
role='Research Analyst',
goal='Provide up-to-date market analysis',
backstory='An expert analyst with a keen eye for market trends.',
tools=[search_tool],
memory=True, # Ativa memória
verbose=True,
max_rpm=None, # Sem limite de requisições por minuto
max_iter=25, # Valor padrão de máximo de iterações
)
```
## Delegação e Autonomia
Controlar a capacidade de um agente delegar tarefas ou fazer perguntas é fundamental para ajustar sua autonomia e a dinâmica de colaboração dentro do framework CrewAI. Por padrão,
o atributo `allow_delegation` agora é definido como `False`, desabilitando para que agentes busquem assistência ou deleguem tarefas conforme necessário. Esse comportamento padrão pode ser alterado para promover resolução colaborativa de problemas e
eficiência dentro do ecossistema CrewAI. Se necessário, a delegação pode ser ativada para atender requisitos operacionais específicos.
### Exemplo: Desabilitando Delegação para um Agente
```python Code
agent = Agent(
role='Content Writer',
goal='Write engaging content on market trends',
backstory='A seasoned writer with expertise in market analysis.',
allow_delegation=True # Habilitando delegação
)
```
## Conclusão
Personalizar agentes no CrewAI definindo seus papéis, objetivos, histórias e ferramentas, juntamente com opções avançadas como personalização de modelo de linguagem, memória, ajustes de performance e preferências de delegação,
proporciona uma equipe de IA sofisticada e preparada para enfrentar desafios complexos.

73
docs/pt-BR/learn/dalle-image-generation.mdx Normal file
View File

@@ -0,0 +1,73 @@
---
title: "Geração de Imagens com DALL-E"
description: "Aprenda a usar o DALL-E para geração de imagens com IA em seus projetos CrewAI"
icon: "image"
---
O CrewAI oferece integração com o DALL-E da OpenAI, permitindo que seus agentes de IA gerem imagens como parte de suas tarefas. Este guia irá orientá-lo sobre como configurar e utilizar a ferramenta DALL-E em seus projetos CrewAI.
## Pré-requisitos
- crewAI instalado (última versão)
- Chave de API OpenAI com acesso ao DALL-E
## Configurando a Ferramenta DALL-E
<Steps>
<Step title="Importe a ferramenta DALL-E">
```python
from crewai_tools import DallETool
```
</Step>
<Step title="Adicione a ferramenta DALL-E na configuração do seu agente">
```python
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'],
tools=[SerperDevTool(), DallETool()], # Add DallETool to the list of tools
allow_delegation=False,
verbose=True
)
```
</Step>
</Steps>
## Utilizando a Ferramenta DALL-E
Depois de adicionar a ferramenta DALL-E ao seu agente, ele poderá gerar imagens baseadas em prompts de texto. A ferramenta retornará uma URL para a imagem gerada, que pode ser utilizada na resposta do agente ou repassada para outros agentes para processamento adicional.
### Exemplo de Configuração de Agente
```yaml
role: >
Pesquisador Sênior de Dados para Perfis do LinkedIn
goal: >
Encontrar perfis detalhados do LinkedIn com base no nome fornecido {name} e domínio {domain}
Gerar uma imagem com o Dall-e baseada no domínio {domain}
backstory: >
Você é um pesquisador experiente com habilidade para encontrar os perfis do LinkedIn mais relevantes.
Conhecido por sua eficiência em navegar no LinkedIn, você se destaca em reunir e apresentar
informações profissionais de forma clara e concisa.
```
### Resultado Esperado
O agente com a ferramenta DALL-E conseguirá gerar a imagem e fornecer uma URL em sua resposta. Você poderá então baixar a imagem.
<Frame>
<img src="/images/enterprise/dall-e-image.png" alt="Imagem DALL-E" />
</Frame>
## Boas Práticas
1. **Seja específico nos prompts de geração de imagem** para obter melhores resultados.
2. **Considere o tempo de geração** - A geração de imagens pode levar algum tempo, então inclua isso no seu planejamento de tarefas.
3. **Siga as políticas de uso** - Sempre cumpra as políticas de uso da OpenAI ao gerar imagens.
## Solução de Problemas
1. **Verifique o acesso à API** - Certifique-se de que sua chave de API OpenAI possui acesso ao DALL-E.
2. **Compatibilidade de versões** - Verifique se você está utilizando a versão mais recente do crewAI e crewai-tools.
3. **Configuração da ferramenta** - Confirme que a ferramenta DALL-E foi corretamente adicionada à lista de ferramentas do agente.

50
docs/pt-BR/learn/force-tool-output-as-result.mdx Normal file
View File

@@ -0,0 +1,50 @@
---
title: Forçar a Saída da Ferramenta como Resultado
description: Aprenda como forçar a saída de uma ferramenta como resultado em uma tarefa de Agent no CrewAI.
icon: wrench-simple
---
## Introdução
No CrewAI, você pode forçar a saída de uma ferramenta como o resultado de uma tarefa de um agent.
Esse recurso é útil quando você deseja garantir que a saída da ferramenta seja capturada e retornada como resultado da tarefa, evitando quaisquer modificações pelo agent durante a execução da tarefa.
## Forçando a Saída da Ferramenta como Resultado
Para forçar a saída da ferramenta como resultado da tarefa de um agent, você precisa definir o parâmetro `result_as_answer` como `True` ao adicionar uma ferramenta ao agent.
Esse parâmetro garante que a saída da ferramenta seja capturada e retornada como resultado da tarefa, sem qualquer modificação pelo agent.
Veja um exemplo de como forçar a saída da ferramenta como resultado da tarefa de um agent:
```python Code
from crewai.agent import Agent
from my_tool import MyCustomTool
# Create a coding agent with the custom tool
coding_agent = Agent(
role="Data Scientist",
goal="Produce amazing reports on AI",
backstory="You work with data and AI",
tools=[MyCustomTool(result_as_answer=True)],
)
# Assuming the tool's execution and result population occurs within the system
task_result = coding_agent.execute_task(task)
```
## Fluxo de Trabalho em Ação
<Steps>
<Step title="Execução da Tarefa">
O agent executa a tarefa utilizando a ferramenta fornecida.
</Step>
<Step title="Saída da Ferramenta">
A ferramenta gera a saída, que é capturada como resultado da tarefa.
</Step>
<Step title="Interação do Agent">
O agent pode refletir e aprender com a ferramenta, mas a saída não é modificada.
</Step>
<Step title="Retorno do Resultado">
A saída da ferramenta é retornada como resultado da tarefa sem quaisquer modificações.
</Step>
</Steps>

111
docs/pt-BR/learn/hierarchical-process.mdx Normal file
View File

@@ -0,0 +1,111 @@
---
title: Processo Hierárquico
description: Um guia abrangente para compreender e aplicar o processo hierárquico em seus projetos CrewAI, atualizado para refletir as práticas de codificação e funcionalidades mais recentes.
icon: sitemap
---
## Introdução
O processo hierárquico no CrewAI introduz uma abordagem estruturada para a gestão de tarefas, simulando hierarquias organizacionais tradicionais para uma delegação e execução eficiente de tarefas.
Esse fluxo de trabalho sistemático melhora os resultados do projeto ao garantir que as tarefas sejam tratadas com máxima eficiência e precisão.
<Tip>
O processo hierárquico foi projetado para alavancar modelos avançados como o GPT-4, otimizando o uso de tokens enquanto lida com tarefas complexas de forma mais eficiente.
</Tip>
## Visão Geral do Processo Hierárquico
Por padrão, as tarefas no CrewAI são gerenciadas por meio de um processo sequencial. No entanto, adotar uma abordagem hierárquica permite uma hierarquia clara na gestão de tarefas,
onde um agente 'gerente' coordena o fluxo de trabalho, delega tarefas e valida os resultados para uma execução eficaz e simplificada. Esse agente gerente pode agora ser
criado automaticamente pelo CrewAI ou explicitamente definido pelo usuário.
### Principais Características
- **Delegação de Tarefas**: Um agente gerente distribui tarefas entre os membros da crew com base em seus papéis e capacidades.
- **Validação de Resultados**: O gerente avalia os resultados para garantir que atendam aos padrões exigidos.
- **Fluxo de Trabalho Eficiente**: Emula estruturas corporativas, oferecendo uma abordagem organizada para a gestão de tarefas.
- **Manipulação de System Prompt**: Opcionalmente, especifique se o sistema deve usar prompts predefinidos.
- **Controle de Stop Words**: Opcionalmente, especifique se stop words devem ser usadas, oferecendo suporte a diversos modelos, incluindo os modelos o1.
- **Respeito à Context Window**: Priorização de contexto relevante ativando o respeito à context window, que agora é o comportamento padrão.
- **Controle de Delegação**: A delegação agora está desativada por padrão para dar controle explícito ao usuário.
- **Máximo de Requisições por Minuto**: Opção configurável para definir o número máximo de requisições por minuto.
- **Máximo de Iterações**: Limitação do número máximo de iterações até a obtenção de uma resposta final.
## Implementando o Processo Hierárquico
Para utilizar o processo hierárquico, é essencial definir explicitamente o atributo de processo como `Process.hierarchical`, já que o comportamento padrão é `Process.sequential`.
Defina uma crew com um gerente designado e estabeleça uma cadeia de comando clara.
<Tip>
Atribua ferramentas no nível do agente para facilitar a delegação e execução de tarefas pelos agentes designados sob a orientação do gerente.
Ferramentas também podem ser especificadas no nível da tarefa, para um controle preciso sobre a disponibilidade de ferramentas durante a execução das tarefas.
</Tip>
<Tip>
Configurar o parâmetro `manager_llm` é fundamental para o processo hierárquico.
O sistema exige a configuração de um LLM do gerente para funcionar corretamente, garantindo tomadas de decisão personalizadas.
</Tip>
```python Code
from crewai import Crew, Process, Agent
# Agents are defined with attributes for backstory, cache, and verbose mode
researcher = Agent(
role='Researcher',
goal='Conduct in-depth analysis',
backstory='Experienced data analyst with a knack for uncovering hidden trends.',
)
writer = Agent(
role='Writer',
goal='Create engaging content',
backstory='Creative writer passionate about storytelling in technical domains.',
)
# Establishing the crew with a hierarchical process and additional configurations
project_crew = Crew(
tasks=[...], # Tasks to be delegated and executed under the manager's supervision
agents=[researcher, writer],
manager_llm="gpt-4o", # Specify which LLM the manager should use
process=Process.hierarchical,
planning=True,
)
```
### Usando um Agente Gerente Personalizado
Alternativamente, você pode criar um agente gerente personalizado com atributos específicos adaptados às necessidades de gestão do seu projeto. Isso oferece maior controle sobre o comportamento e as capacidades do gerente.
```python
# Define a custom manager agent
manager = Agent(
role="Project Manager",
goal="Efficiently manage the crew and ensure high-quality task completion",
backstory="You're an experienced project manager, skilled in overseeing complex projects and guiding teams to success.",
allow_delegation=True,
)
# Use the custom manager in your crew
project_crew = Crew(
tasks=[...],
agents=[researcher, writer],
manager_agent=manager, # Use your custom manager agent
process=Process.hierarchical,
planning=True,
)
```
<Tip>
Para mais detalhes sobre a criação e personalização de um agente gerente, confira a [documentação do Custom Manager Agent](https://docs.crewai.com/how-to/custom-manager-agent#custom-manager-agent).
</Tip>
### Fluxo de Trabalho na Prática
1. **Atribuição de Tarefas**: O gerente atribui as tarefas estrategicamente, considerando as capacidades de cada agente e as ferramentas disponíveis.
2. **Execução e Revisão**: Os agentes concluem suas tarefas com a opção de execução assíncrona e funções de callback para fluxos de trabalho otimizados.
3. **Progresso Sequencial das Tarefas**: Apesar de ser um processo hierárquico, as tarefas seguem uma ordem lógica para um progresso fluido, facilitado pela supervisão do gerente.
## Conclusão
Adotar o processo hierárquico no CrewAI, com as configurações corretas e o entendimento das capacidades do sistema, facilita uma abordagem organizada e eficiente para o gerenciamento de projetos.
Aproveite os recursos avançados e as personalizações para ajustar o fluxo de trabalho conforme suas necessidades, garantindo a execução ideal das tarefas e o sucesso do projeto.

78
docs/pt-BR/learn/human-in-the-loop.mdx Normal file
View File

@@ -0,0 +1,78 @@
---
title: "Workflows Human-in-the-Loop (HITL)"
description: "Aprenda como implementar workflows Human-in-the-Loop na CrewAI para aprimorar a tomada de decisões"
icon: "user-check"
---
Human-in-the-Loop (HITL) é uma abordagem poderosa que combina a inteligência artificial com a experiência humana para aprimorar a tomada de decisões e melhorar os resultados das tarefas. Este guia mostra como implementar HITL dentro da CrewAI.
## Configurando Workflows HITL
<Steps>
<Step title="Configure sua Tarefa">
Configure sua tarefa com a entrada humana habilitada:
<Frame>
<img src="/images/enterprise/crew-human-input.png" alt="Entrada Humana Crew" />
</Frame>
</Step>
<Step title="Forneça a URL do Webhook">
Ao iniciar seu crew, inclua uma URL de webhook para entrada humana:
<Frame>
<img src="/images/enterprise/crew-webhook-url.png" alt="URL do Webhook Crew" />
</Frame>
</Step>
<Step title="Receba Notificação do Webhook">
Assim que o crew concluir a tarefa que requer entrada humana, você receberá uma notificação de webhook contendo:
- Execution ID
- Task ID
- Task output
</Step>
<Step title="Revise o Resultado da Tarefa">
O sistema irá pausar no estado `Pending Human Input`. Revise cuidadosamente o resultado da tarefa.
</Step>
<Step title="Envie o Feedback Humano">
Chame o endpoint de retomada do seu crew com as seguintes informações:
<Frame>
<img src="/images/enterprise/crew-resume-endpoint.png" alt="Endpoint de Retomada Crew" />
</Frame>
<Warning>
**Impacto do Feedback na Execução da Tarefa**:
É fundamental ter cuidado ao fornecer feedback, pois todo o conteúdo do feedback será incorporado como contexto adicional para execuções futuras da tarefa.
</Warning>
Isso significa:
- Todas as informações do seu feedback passam a fazer parte do contexto da tarefa.
- Detalhes irrelevantes podem influenciar negativamente.
- Feedback conciso e relevante ajuda a manter o foco e a eficiência da tarefa.
- Sempre revise seu feedback cuidadosamente antes de enviar para garantir que contenha apenas informações pertinentes que irão guiar positivamente a execução da tarefa.
</Step>
<Step title="Lidar com Feedback Negativo">
Se você fornecer um feedback negativo:
- O crew irá tentar novamente a tarefa com o contexto adicionado do seu feedback.
- Você receberá outra notificação de webhook para nova revisão.
- Repita os passos 4-6 até ficar satisfeito.
</Step>
<Step title="Continuação da Execução">
Quando você enviar um feedback positivo, a execução prosseguirá para as próximas etapas.
</Step>
</Steps>
## Melhores Práticas
- **Seja Específico**: Forneça feedback claro e acionável que trate diretamente da tarefa em questão
- **Mantenha-se Relevante**: Inclua apenas informações que ajudem a melhorar a execução da tarefa
- **Seja Ágil**: Responda rapidamente às solicitações HITL para evitar atrasos no fluxo
- **Reveja Cuidadosamente**: Verifique seu feedback antes de enviar para garantir a precisão
## Casos de Uso Comuns
Workflows HITL são particularmente valiosos para:
- Garantia de qualidade e validação
- Cenários de tomada de decisão complexa
- Operações sensíveis ou de alto risco
- Tarefas criativas que requerem julgamento humano
- Revisões de conformidade e regulamentação

98
docs/pt-BR/learn/human-input-on-execution.mdx Normal file
View File

@@ -0,0 +1,98 @@
---
title: Input Humano na Execução
description: Integrando o CrewAI com input humano durante a execução em processos complexos de tomada de decisão e aproveitando ao máximo todos os atributos e ferramentas do agente.
icon: user-check
---
## Input humano na execução dos agentes
O input humano é fundamental em vários cenários de execução de agentes, permitindo que os agentes solicitem informações adicionais ou esclarecimentos quando necessário.
Esse recurso é especialmente útil em processos complexos de tomada de decisão ou quando os agentes precisam de mais detalhes para concluir uma tarefa de forma eficaz.
## Usando input humano com CrewAI
Para integrar input humano durante a execução do agente, defina o parâmetro `human_input` na definição da tarefa. Quando ativado, o agente solicitará informações ao usuário antes de fornecer sua resposta final.
Esse input pode oferecer contexto extra, esclarecer ambiguidades ou validar a saída produzida pelo agente.
### Exemplo:
```shell
pip install crewai
```
```python Code
import os
from crewai import Agent, Task, Crew
from crewai_tools import SerperDevTool
os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key
os.environ["OPENAI_API_KEY"] = "Your Key"
# Loading Tools
search_tool = SerperDevTool()
# Define your agents with roles, goals, tools, and additional attributes
researcher = Agent(
role='Senior Research Analyst',
goal='Uncover cutting-edge developments in AI and data science',
backstory=(
"You are a Senior Research Analyst at a leading tech think tank. "
"Your expertise lies in identifying emerging trends and technologies in AI and data science. "
"You have a knack for dissecting complex data and presenting actionable insights."
),
verbose=True,
allow_delegation=False,
tools=[search_tool]
)
writer = Agent(
role='Tech Content Strategist',
goal='Craft compelling content on tech advancements',
backstory=(
"You are a renowned Tech Content Strategist, known for your insightful and engaging articles on technology and innovation. "
"With a deep understanding of the tech industry, you transform complex concepts into compelling narratives."
),
verbose=True,
allow_delegation=True,
tools=[search_tool],
cache=False, # Disable cache for this agent
)
# Create tasks for your agents
task1 = Task(
description=(
"Conduct a comprehensive analysis of the latest advancements in AI in 2025. "
"Identify key trends, breakthrough technologies, and potential industry impacts. "
"Compile your findings in a detailed report. "
"Make sure to check with a human if the draft is good before finalizing your answer."
),
expected_output='A comprehensive full report on the latest AI advancements in 2025, leave nothing out',
agent=researcher,
human_input=True
)
task2 = Task(
description=(
"Using the insights from the researcher\'s report, develop an engaging blog post that highlights the most significant AI advancements. "
"Your post should be informative yet accessible, catering to a tech-savvy audience. "
"Aim for a narrative that captures the essence of these breakthroughs and their implications for the future."
),
expected_output='A compelling 3 paragraphs blog post formatted as markdown about the latest AI advancements in 2025',
agent=writer,
human_input=True
)
# Instantiate your crew with a sequential process
crew = Crew(
agents=[researcher, writer],
tasks=[task1, task2],
verbose=True,
memory=True,
planning=True # Enable planning feature for the crew
)
# Get your crew to work!
result = crew.kickoff()
print("######################")
print(result)
```

123
docs/pt-BR/learn/kickoff-async.mdx Normal file
View File

@@ -0,0 +1,123 @@
---
title: Inicie uma Crew de Forma Assíncrona
description: Inicie uma Crew de Forma Assíncrona
icon: rocket-launch
---
## Introdução
A CrewAI oferece a capacidade de iniciar uma crew de forma assíncrona, permitindo que você comece a execução da crew de maneira não bloqueante.
Esse recurso é especialmente útil quando você deseja executar múltiplas crews simultaneamente ou quando precisa realizar outras tarefas enquanto a crew está em execução.
## Execução Assíncrona de Crew
Para iniciar uma crew de forma assíncrona, utilize o método `kickoff_async()`. Este método inicia a execução da crew em uma thread separada, permitindo que a thread principal continue executando outras tarefas.
### Assinatura do Método
```python Code
def kickoff_async(self, inputs: dict) -> CrewOutput:
```
### Parâmetros
- `inputs` (dict): Um dicionário contendo os dados de entrada necessários para as tarefas.
### Retorno
- `CrewOutput`: Um objeto que representa o resultado da execução da crew.
## Possíveis Casos de Uso
- **Geração Paralela de Conteúdo**: Inicie múltiplas crews independentes de forma assíncrona, cada uma responsável por gerar conteúdo sobre temas diferentes. Por exemplo, uma crew pode pesquisar e redigir um artigo sobre tendências em IA, enquanto outra gera posts para redes sociais sobre o lançamento de um novo produto. Cada crew atua de forma independente, permitindo a escala eficiente da produção de conteúdo.
- **Tarefas Conjuntas de Pesquisa de Mercado**: Lance múltiplas crews de forma assíncrona para realizar pesquisas de mercado em paralelo. Uma crew pode analisar tendências do setor, outra examinar estratégias de concorrentes e ainda outra avaliar o sentimento do consumidor. Cada crew conclui sua tarefa de forma independente, proporcionando insights mais rápidos e abrangentes.
- **Módulos Independentes de Planejamento de Viagem**: Execute crews separadas para planejar diferentes aspectos de uma viagem de forma independente. Uma crew pode cuidar das opções de voo, outra das acomodações e uma terceira do planejamento das atividades. Cada crew trabalha de maneira assíncrona, permitindo que os vários componentes da viagem sejam planejados ao mesmo tempo e de maneira independente, para resultados mais rápidos.
## Exemplo: Execução Assíncrona de uma Única Crew
Veja um exemplo de como iniciar uma crew de forma assíncrona utilizando asyncio e aguardando o resultado:
```python Code
import asyncio
from crewai import Crew, Agent, Task
# Create an agent with code execution enabled
coding_agent = Agent(
role="Python Data Analyst",
goal="Analyze data and provide insights using Python",
backstory="You are an experienced data analyst with strong Python skills.",
allow_code_execution=True
)
# Create a task that requires code execution
data_analysis_task = Task(
description="Analyze the given dataset and calculate the average age of participants. Ages: {ages}",
agent=coding_agent,
expected_output="The average age of the participants."
)
# Create a crew and add the task
analysis_crew = Crew(
agents=[coding_agent],
tasks=[data_analysis_task]
)
# Async function to kickoff the crew asynchronously
async def async_crew_execution():
result = await analysis_crew.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]})
print("Crew Result:", result)
# Run the async function
asyncio.run(async_crew_execution())
```
## Exemplo: Execução Assíncrona de Múltiplas Crews
Neste exemplo, mostraremos como iniciar múltiplas crews de forma assíncrona e aguardar todas serem concluídas usando `asyncio.gather()`:
```python Code
import asyncio
from crewai import Crew, Agent, Task
# Create an agent with code execution enabled
coding_agent = Agent(
role="Python Data Analyst",
goal="Analyze data and provide insights using Python",
backstory="You are an experienced data analyst with strong Python skills.",
allow_code_execution=True
)
# Create tasks that require code execution
task_1 = Task(
description="Analyze the first dataset and calculate the average age of participants. Ages: {ages}",
agent=coding_agent,
expected_output="The average age of the participants."
)
task_2 = Task(
description="Analyze the second dataset and calculate the average age of participants. Ages: {ages}",
agent=coding_agent,
expected_output="The average age of the participants."
)
# Create two crews and add tasks
crew_1 = Crew(agents=[coding_agent], tasks=[task_1])
crew_2 = Crew(agents=[coding_agent], tasks=[task_2])
# Async function to kickoff multiple crews asynchronously and wait for all to finish
async def async_multiple_crews():
# Create coroutines for concurrent execution
result_1 = crew_1.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]})
result_2 = crew_2.kickoff_async(inputs={"ages": [20, 22, 24, 28, 30]})
# Wait for both crews to finish
results = await asyncio.gather(result_1, result_2)
for i, result in enumerate(results, 1):
print(f"Crew {i} Result:", result)
# Run the async function
asyncio.run(async_multiple_crews())
```

53
docs/pt-BR/learn/kickoff-for-each.mdx Normal file
View File

@@ -0,0 +1,53 @@
---
title: Kickoff Crew para Cada
description: Kickoff Crew para Cada Item em uma Lista
icon: at
---
## Introdução
A CrewAI oferece a capacidade de iniciar um crew para cada item em uma lista, permitindo que você execute o crew para cada item da lista.
Esse recurso é particularmente útil quando é necessário realizar o mesmo conjunto de tarefas para vários itens.
## Iniciando um Crew para Cada Item
Para iniciar um crew para cada item em uma lista, utilize o método `kickoff_for_each()`.
Esse método executa o crew para cada item da lista, permitindo o processamento eficiente de múltiplos itens.
Veja um exemplo de como iniciar um crew para cada item em uma lista:
```python Code
from crewai import Crew, Agent, Task
# Create an agent with code execution enabled
coding_agent = Agent(
role="Python Data Analyst",
goal="Analyze data and provide insights using Python",
backstory="You are an experienced data analyst with strong Python skills.",
allow_code_execution=True
)
# Create a task that requires code execution
data_analysis_task = Task(
description="Analyze the given dataset and calculate the average age of participants. Ages: {ages}",
agent=coding_agent,
expected_output="The average age calculated from the dataset"
)
# Create a crew and add the task
analysis_crew = Crew(
agents=[coding_agent],
tasks=[data_analysis_task],
verbose=True,
memory=False
)
datasets = [
{ "ages": [25, 30, 35, 40, 45] },
{ "ages": [20, 25, 30, 35, 40] },
{ "ages": [30, 35, 40, 45, 50] }
]
# Execute the crew
result = analysis_crew.kickoff_for_each(inputs=datasets)
```

204
docs/pt-BR/learn/llm-connections.mdx Normal file
View File

@@ -0,0 +1,204 @@
---
title: Conecte-se a qualquer LLM
description: Guia abrangente sobre como integrar o CrewAI a diversos Large Language Models (LLMs) usando o LiteLLM, incluindo provedores compatíveis e opções de configuração.
icon: brain-circuit
---
## Conecte o CrewAI a LLMs
O CrewAI utiliza o LiteLLM para conectar-se a uma grande variedade de Modelos de Linguagem (LLMs). Essa integração proporciona grande versatilidade, permitindo que você utilize modelos de inúmeros provedores por meio de uma interface simples e unificada.
<Note>
Por padrão, o CrewAI usa o modelo `gpt-4o-mini`. Isso é determinado pela variável de ambiente `OPENAI_MODEL_NAME`, que tem como padrão "gpt-4o-mini" se não for definida.
Você pode facilmente configurar seus agentes para usar um modelo ou provedor diferente, conforme descrito neste guia.
</Note>
## Provedores Compatíveis
O LiteLLM oferece suporte a uma ampla gama de provedores, incluindo, mas não se limitando a:
- OpenAI
- Anthropic
- Google (Vertex AI, Gemini)
- Azure OpenAI
- AWS (Bedrock, SageMaker)
- Cohere
- VoyageAI
- Hugging Face
- Ollama
- Mistral AI
- Replicate
- Together AI
- AI21
- Cloudflare Workers AI
- DeepInfra
- Groq
- SambaNova
- [NVIDIA NIMs](https://docs.api.nvidia.com/nim/reference/models-1)
- E muitos outros!
Para uma lista completa e sempre atualizada dos provedores suportados, consulte a [documentação de Provedores do LiteLLM](https://docs.litellm.ai/docs/providers).
## Alterando a LLM
Para utilizar uma LLM diferente com seus agentes CrewAI, você tem várias opções:
<Tabs>
<Tab title="Usando um Identificador de String">
Passe o nome do modelo como uma string ao inicializar o agente:
<CodeGroup>
```python Code
from crewai import Agent
# Usando o GPT-4 da OpenAI
openai_agent = Agent(
role='OpenAI Expert',
goal='Provide insights using GPT-4',
backstory="An AI assistant powered by OpenAI's latest model.",
llm='gpt-4'
)
# Usando o Claude da Anthropic
claude_agent = Agent(
role='Anthropic Expert',
goal='Analyze data using Claude',
backstory="An AI assistant leveraging Anthropic's language model.",
llm='claude-2'
)
```
</CodeGroup>
</Tab>
<Tab title="Usando a Classe LLM">
Para uma configuração mais detalhada, utilize a classe LLM:
<CodeGroup>
```python Code
from crewai import Agent, LLM
llm = LLM(
model="gpt-4",
temperature=0.7,
base_url="https://api.openai.com/v1",
api_key="your-api-key-here"
)
agent = Agent(
role='Customized LLM Expert',
goal='Provide tailored responses',
backstory="An AI assistant with custom LLM settings.",
llm=llm
)
```
</CodeGroup>
</Tab>
</Tabs>
## Opções de Configuração
Ao configurar uma LLM para o seu agente, você tem acesso a uma variedade de parâmetros:
| Parâmetro | Tipo | Descrição |
|:----------|:-----:|:-------------|
| **model** | `str` | O nome do modelo a ser utilizado (ex.: "gpt-4", "claude-2") |
| **temperature** | `float` | Controla o grau de aleatoriedade nas respostas (0.0 a 1.0) |
| **max_tokens** | `int` | Número máximo de tokens a serem gerados |
| **top_p** | `float` | Controla a diversidade das respostas (0.0 a 1.0) |
| **frequency_penalty** | `float` | Penaliza novos tokens com base na frequência em que já apareceram no texto |
| **presence_penalty** | `float` | Penaliza novos tokens com base na presença deles no texto até o momento |
| **stop** | `str`, `List[str]` | Sequência(s) que interrompem a geração do texto |
| **base_url** | `str` | URL base do endpoint da API |
| **api_key** | `str` | Sua chave de API para autenticação |
Para uma lista completa de parâmetros e suas respectivas descrições, consulte a documentação da classe LLM.
## Conectando-se a LLMs Compatíveis com OpenAI
Você pode se conectar a LLMs compatíveis com a OpenAI usando variáveis de ambiente ou definindo atributos específicos na classe LLM:
<Tabs>
<Tab title="Usando Variáveis de Ambiente">
<CodeGroup>
```python Generic
import os
os.environ["OPENAI_API_KEY"] = "your-api-key"
os.environ["OPENAI_API_BASE"] = "https://api.your-provider.com/v1"
os.environ["OPENAI_MODEL_NAME"] = "your-model-name"
```
```python Google
import os
# Exemplo usando a API compatível com OpenAI do Gemini.
os.environ["OPENAI_API_KEY"] = "your-gemini-key" # Deve começar com AIza...
os.environ["OPENAI_API_BASE"] = "https://generativelanguage.googleapis.com/v1beta/openai/"
os.environ["OPENAI_MODEL_NAME"] = "openai/gemini-2.0-flash" # Adicione aqui seu modelo do Gemini, sob openai/
```
</CodeGroup>
</Tab>
<Tab title="Usando Atributos da Classe LLM">
<CodeGroup>
```python Generic
llm = LLM(
model="custom-model-name",
api_key="your-api-key",
base_url="https://api.your-provider.com/v1"
)
agent = Agent(llm=llm, ...)
```
```python Google
# Exemplo usando a API compatível com OpenAI do Gemini
llm = LLM(
model="openai/gemini-2.0-flash",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
api_key="your-gemini-key", # Deve começar com AIza...
)
agent = Agent(llm=llm, ...)
```
</CodeGroup>
</Tab>
</Tabs>
## Utilizando Modelos Locais com Ollama
Para modelos locais como os oferecidos pelo Ollama:
<Steps>
<Step title="Baixe e instale o Ollama">
[Clique aqui para baixar e instalar o Ollama](https://ollama.com/download)
</Step>
<Step title="Puxe o modelo desejado">
Por exemplo, execute `ollama pull llama3.2` para baixar o modelo.
</Step>
<Step title="Configure seu agente">
<CodeGroup>
```python Code
agent = Agent(
role='Local AI Expert',
goal='Process information using a local model',
backstory="An AI assistant running on local hardware.",
llm=LLM(model="ollama/llama3.2", base_url="http://localhost:11434")
)
```
</CodeGroup>
</Step>
</Steps>
## Alterando a URL Base da API
Você pode alterar a URL base da API para qualquer provedor de LLM definindo o parâmetro `base_url`:
```python Code
llm = LLM(
model="custom-model-name",
base_url="https://api.your-provider.com/v1",
api_key="your-api-key"
)
agent = Agent(llm=llm, ...)
```
Isso é particularmente útil ao trabalhar com APIs compatíveis com a OpenAI ou quando você precisa especificar um endpoint diferente para o provedor escolhido.
## Conclusão
Ao utilizar o LiteLLM, o CrewAI oferece integração transparente com uma vasta gama de LLMs. Essa flexibilidade permite que você escolha o modelo mais adequado para sua necessidade específica, seja priorizando desempenho, custo-benefício ou implantação local. Lembre-se de consultar a [documentação do LiteLLM](https://docs.litellm.ai/docs/) para obter as informações mais atualizadas sobre modelos suportados e opções de configuração.

727
docs/pt-BR/learn/llm-selection-guide.mdx Normal file
View File

@@ -0,0 +1,727 @@
---
title: 'Guia Estratégico de Seleção de LLMs'
description: 'Framework estratégico para escolher o LLM certo para seus agentes CrewAI e escrever definições eficazes de tarefas e agentes'
icon: 'brain-circuit'
---
## A Abordagem CrewAI para Seleção de LLMs
Em vez de recomendações prescritivas de modelos, defendemos um **framework de pensamento** que ajude você a tomar decisões informadas com base no seu caso de uso, restrições e requisitos específicos. O cenário de LLMs evolui rapidamente, com novos modelos surgindo regularmente e os existentes sendo atualizados frequentemente. O que mais importa é desenvolver uma abordagem sistemática de avaliação que permaneça relevante independentemente dos modelos disponíveis no momento.
<Note>
Este guia foca em pensamento estratégico em vez de recomendações de modelos específicos, já que o cenário dos LLMs evolui rapidamente.
</Note>
## Framework de Decisão Rápida
<Steps>
<Step title="Analise Suas Tarefas">
Comece entendendo profundamente o que suas tarefas realmente exigem. Considere a complexidade cognitiva envolvida, a profundidade de raciocínio necessária, o formato dos resultados esperados e a quantidade de contexto que o modelo precisará processar. Essa análise fundamental guiará todas as decisões seguintes.
</Step>
<Step title="Mapeie as Capacidades dos Modelos">
Assim que você compreende seus requisitos, mapeie-os para as forças dos modelos. Diferentes famílias de modelos se destacam em diferentes tipos de trabalho; alguns são otimizados para raciocínio e análise, outros para criatividade e geração de conteúdo, e outros para velocidade e eficiência.
</Step>
<Step title="Considere Restrições">
Leve em conta suas reais restrições operacionais, incluindo limitações orçamentárias, requisitos de latência, necessidades de privacidade de dados e capacidades de infraestrutura. O melhor modelo teoricamente pode não ser a melhor escolha prática para sua situação.
</Step>
<Step title="Teste e Itere">
Comece com modelos confiáveis e bem conhecidos e otimize com base no desempenho real no seu caso de uso. Os resultados práticos frequentemente diferem dos benchmarks teóricos, então testes empíricos são cruciais.
</Step>
</Steps>
## Framework Central de Seleção
### a. Pensamento Orientado à Tarefa
O passo mais crítico na seleção de LLMs é entender o que sua tarefa realmente exige. Frequentemente, equipes escolhem modelos com base em reputação geral ou pontuações de benchmark, sem analisar cuidadosamente suas necessidades específicas. Essa abordagem leva tanto ao superdimensionamento de tarefas simples usando modelos caros e complexos quanto à subutilização em tarefas sofisticadas com modelos sem as capacidades necessárias.
<Tabs>
<Tab title="Complexidade de Raciocínio">
- **Tarefas Simples** representam a maioria do trabalho diário de IA e incluem seguir instruções básicas, processar dados simples e formatação elementar. Estas tarefas geralmente têm entradas e saídas claras, com mínima ambiguidade. A carga cognitiva é baixa e o modelo precisa apenas seguir instruções explícitas, não realizar raciocínio complexo.
- **Tarefas Complexas** exigem raciocínio de múltiplas etapas, pensamento estratégico e a capacidade de lidar com informações ambíguas ou incompletas. Podem envolver análise de múltiplas fontes de dados, desenvolvimento de estratégias abrangentes ou resolução de problemas que precisam ser decompostos em componentes menores. O modelo deve manter o contexto ao longo de várias etapas de raciocínio e frequentemente precisa inferir informações não explicitamente declaradas.
- **Tarefas Criativas** exigem um tipo diferente de capacidade cognitiva, focada em gerar conteúdo novo, envolvente e adequado ao contexto. Isso inclui storytelling, criação de textos de marketing e solução criativa de problemas. O modelo deve compreender nuances, tom e público, produzindo conteúdo autêntico e envolvente, não apenas fórmulas.
</Tab>
<Tab title="Requisitos de Saída">
- **Dados Estruturados** exigem precisão e consistência na adesão ao formato. Ao trabalhar com JSON, XML ou formatos de banco de dados, o modelo deve produzir saídas sintaticamente corretas, que possam ser processadas programaticamente. Essas tarefas possuem requisitos rígidos de validação e pouca tolerância a erros de formato, tornando a confiabilidade mais importante que a criatividade.
- **Conteúdo Criativo** requer equilíbrio entre competência técnica e criatividade. O modelo precisa compreender o público, tom e voz da marca, ao mesmo tempo em que produz conteúdo que engaja leitores e atinge objetivos comunicativos específicos. A qualidade aqui é mais subjetiva e exige modelos capazes de adaptar o estilo de escrita a diferentes contextos e propósitos.
- **Conteúdo Técnico** situa-se entre dados estruturados e conteúdo criativo, demandando precisão e clareza. Documentação, geração de código e análises técnicas precisam ser exatas e completas, mas ainda assim acessíveis ao público-alvo. O modelo deve entender conceitos técnicos complexos e comunicá-los de forma eficaz.
</Tab>
<Tab title="Necessidades de Contexto">
- **Contexto Curto** envolve tarefas imediatas e focalizadas, onde o modelo processa informações limitadas rapidamente. São interações transacionais em que velocidade e eficiência importam mais do que compreensão profunda. O modelo não precisa manter histórico extenso ou processar grandes documentos.
- **Contexto Longo** é necessário ao lidar com documentos substanciais, conversas extensas ou tarefas complexas de múltiplas partes. O modelo precisa manter coerência ao longo de milhares de tokens, referenciando informações anteriores com precisão. Essencial para análise de documentos, pesquisa abrangente e sistemas de diálogo sofisticados.
- **Contexto Muito Longo** ultrapassa os limites do possível hoje, com processamento de documentos massivos, síntese de pesquisas extensas ou interações multi-sessão. São casos que exigem modelos projetados especificamente para lidar com contexto estendido e envolvem trade-offs entre extensão e velocidade.
</Tab>
</Tabs>
### b. Mapeamento de Capacidades do Modelo
Entender as capacidades dos modelos exige ir além do marketing e dos benchmarks, analisando forças e limitações fundamentais das arquiteturas e métodos de treinamento.
<AccordionGroup>
<Accordion title="Modelos de Raciocínio" icon="brain">
Modelos de raciocínio formam uma categoria especializada, projetada para tarefas de pensamento complexo e de múltiplas etapas. Eles se destacam na resolução de problemas que requerem análise cuidadosa, planejamento estratégico ou decomposição sistemática. Normalmente aplicam técnicas como chain-of-thought ou tree-of-thought para conduzir o raciocínio passo a passo.
O ponto forte é manter consistência lógica em cadeias longas de raciocínio e decompor problemas complexos em partes gerenciáveis. São especialmente valiosos para planejamento estratégico, análise complexa e situações onde a qualidade do raciocínio importa mais que a velocidade.
Entretanto, há trade-offs em termos de custo e velocidade. Podem ser menos adequados para tarefas criativas ou operações simples, onde suas capacidades avançadas não são necessárias. Considere-os quando as tarefas realmente se beneficiarem dessa análise detalhada.
</Accordion>
<Accordion title="Modelos de Uso Geral" icon="microchip">
Modelos de uso geral oferecem uma abordagem equilibrada, com desempenho sólido em uma ampla gama de tarefas, sem especialização extrema. São treinados em conjuntos de dados diversificados e otimizados para versatilidade.
A principal vantagem é a confiabilidade previsível em diversos trabalhos: pesquisa, análise, criação de conteúdo, processamento de dados. São ótimas opções iniciais para equipes que buscam consistência ao lidar com fluxos variados.
Embora não atinjam picos de desempenho como modelos especializados, oferecem simplicidade operacional e baixa complexidade na gestão. São o melhor ponto de partida para novos projetos, permitindo descobertas de necessidades antes de avançar para otimizações.
</Accordion>
<Accordion title="Modelos Rápidos & Eficientes" icon="bolt">
Modelos rápidos e eficientes priorizam velocidade, custo e eficiência de recursos, em vez de raciocínio sofisticado. São otimizados para cenários de alto volume onde respostas rápidas e baixos custos são mais importantes que compreensão ou criatividade profunda.
Brilham em operações rotineiras, processamento simples de dados, chamadas de funções e tarefas de alto volume. Aplicações que processam muitos pedidos rapidamente ou operam sob restrições orçamentárias se beneficiam desses modelos.
O ponto crucial é garantir que suas capacidades atendam às exigências da tarefa. Podem não atender tarefas que exijam entendimento profundo, raciocínio complexo ou geração de conteúdo sofisticado. São ideais para tarefas rotineiras bem definidas.
</Accordion>
<Accordion title="Modelos Criativos" icon="pen">
Modelos criativos são otimizados para geração de conteúdo, qualidade de escrita e pensamento inovador. Excelentes na compreensão de nuances, tom e estilo, produzindo conteúdo envolvente e natural.
O ponto forte está em adaptar o estilo para diferentes públicos, manter voz e tom consistentes e engajar leitores. Performam melhor em storytelling, textos publicitários, comunicações de marca e outras tarefas com criatividade como foco.
Ao selecionar esses modelos, considere não apenas a habilidade de gerar texto, mas a compreensão de público, contexto e objetivo. Os melhores modelos criativos adaptam a saída à voz da marca, diferentes segmentos e mantêm consistência em peças longas.
</Accordion>
<Accordion title="Modelos Open Source" icon="code">
Modelos open source oferecem vantagens em controle de custos, potencial de customização, privacidade de dados e flexibilidade de deployment. Podem ser rodados localmente ou em infraestrutura própria, dando controle total sobre dados e comportamento.
Os principais benefícios incluem eliminação de custos por token, possibilidade de fine-tuning, privacidade total e independência de fornecedores externos. Perfeitos para organizações com necessidade de privacidade, orçamento limitado ou desejo de customização.
Contudo, requerem maior expertise técnica para implantar e manter. Considere custos de infraestrutura, complexidade de gestão e esforços contínuos de atualização e otimização ao avaliar modelos open source. O custo total pode ser maior que o de alternativas em nuvem devido a esse overhead.
</Accordion>
</AccordionGroup>
## Padrões Estratégicos de Configuração
### a. Abordagem Multi-Modelo
<Tip>
Use diferentes modelos para diferentes propósitos dentro da mesma crew para otimizar desempenho e custos.
</Tip>
As implementações CrewAI mais sofisticadas empregam múltiplos modelos estrategicamente, designando-os conforme as funções e necessidades dos agentes. Assim, é possível otimizar desempenho e custos usando o modelo mais adequado para cada tipo de tarefa.
Agentes de planejamento se beneficiam de modelos de raciocínio para pensamento estratégico e análise multi-etapas. Esses agentes funcionam como o "cérebro" da operação. Agentes de conteúdo têm melhor desempenho com modelos criativos focados em qualidade de escrita e engajamento. Agentes de processamento, responsáveis por operações rotineiras, podem usar modelos eficientes priorizando velocidade.
**Exemplo: Crew de Pesquisa e Análise**
```python
from crewai import Agent, Task, Crew, LLM
# Modelo de raciocínio para planejamento estratégico
manager_llm = LLM(model="gemini-2.5-flash-preview-05-20", temperature=0.1)
# Modelo criativo para gerar conteúdo
content_llm = LLM(model="claude-3-5-sonnet-20241022", temperature=0.7)
# Modelo eficiente para processamento de dados
processing_llm = LLM(model="gpt-4o-mini", temperature=0)
research_manager = Agent(
role="Research Strategy Manager",
goal="Develop comprehensive research strategies and coordinate team efforts",
backstory="Expert research strategist with deep analytical capabilities",
llm=manager_llm, # Modelo de alto nível para raciocínio complexo
verbose=True
)
content_writer = Agent(
role="Research Content Writer",
goal="Transform research findings into compelling, well-structured reports",
backstory="Skilled writer who excels at making complex topics accessible",
llm=content_llm, # Modelo criativo para conteúdo envolvente
verbose=True
)
data_processor = Agent(
role="Data Analysis Specialist",
goal="Extract and organize key data points from research sources",
backstory="Detail-oriented analyst focused on accuracy and efficiency",
llm=processing_llm, # Modelo rápido para tarefas rotineiras
verbose=True
)
crew = Crew(
agents=[research_manager, content_writer, data_processor],
tasks=[...], # Suas tarefas específicas
manager_llm=manager_llm, # Manager usa o modelo de raciocínio
verbose=True
)
```
O segredo do sucesso na implementação multi-modelo está em entender como os agentes interagem e garantir que as capacidades dos modelos estejam alinhadas às responsabilidades. Isso exige planejamento estratégico, mas traz ganhos significativos em qualidade dos resultados e eficiência operacional.
### b. Seleção Específica por Componente
<Tabs>
<Tab title="Manager LLM">
O manager LLM desempenha papel central em fluxos hierárquicos CrewAI, coordenando agentes e tarefas. Este modelo precisa se destacar em delegação, priorização de tarefas e manutenção de contexto em várias operações simultâneas.
LLMs de manager eficazes exigem forte raciocínio para delegar bem, desempenho consistente para coordenar previsivelmente e excelente gestão de contexto para acompanhar o estado dos agentes. O modelo deve entender capacidades e limitações dos agentes enquanto otimiza a alocação de tarefas.
O custo é especialmente relevante, já que este LLM participa de todas as operações. O modelo precisa entregar capacidades suficientes, sem o preço premium de opções sofisticadas demais, buscando sempre o equilíbrio entre performance e valor.
</Tab>
<Tab title="Function Calling LLM">
LLMs de function calling gerenciam o uso de ferramentas por todos os agentes, sendo críticos em crews que dependem fortemente de APIs externas e ferramentas. Devem ser precisos na extração de parâmetros e no processamento das respostas.
As características mais importantes são precisão e confiabilidade, não criatividade ou raciocínio avançado. O modelo deve extrair parâmetros corretos de comandos em linguagem natural consistentemente e processar respostas de ferramentas adequadamente. Velocidade também importa, pois o uso de ferramentas pode envolver múltiplas idas e vindas de informação.
Muitas equipes descobrem que modelos especializados em function calling ou de uso geral com forte suporte a ferramentas funcionam melhor do que modelos criativos ou de raciocínio nesse papel. O fundamental é assegurar que o modelo consiga converter instruções em chamadas estruturadas sem falhas.
</Tab>
<Tab title="Sobrescritas Específicas de Agente">
Agentes individuais podem sobrescrever o LLM do nível da crew quando suas necessidades diferem significativamente das do restante. Isso permite otimização pontual, mantendo a simplicidade operacional para os demais agentes.
Considere sobrescritas quando a função do agente exige capacidades distintas. Por exemplo, um agente de redação criativa pode se beneficiar de um LLM otimizado para geração de conteúdo, enquanto um analista de dados pode preferir um modelo voltado ao raciocínio.
O desafio é balancear otimização com complexidade operacional. Cada modelo adicional aumenta a complexidade de deployment, monitoramento e custos. Foque em sobrescritas apenas quando a melhoria justificar essa complexidade.
</Tab>
</Tabs>
## Framework de Definição de Tarefas
### a. Foque em Clareza, Não em Complexidade
Definir bem as tarefas é frequentemente mais importante do que a seleção do modelo no resultado gerado pelos agentes CrewAI. Tarefas bem formuladas orientam claramente mesmo modelos simples a terem bom desempenho. Já tarefas mal definidas prejudicam até os modelos mais avançados.
<AccordionGroup>
<Accordion title="Descrições de Tarefas Eficazes" icon="list-check">
As melhores descrições de tarefas equilibram detalhamento e clareza. Devem definir o objetivo de forma clara e sem ambiguidade, além de explicar o método a ser usado com detalhes que permitam ao agente agir corretamente.
Descrições eficazes incluem contexto relevante e restrições, ajudando o agente a entender o propósito maior e quaisquer limitações. Divida trabalhos complexos em etapas gerenciáveis em vez de objetivos genéricos e sobrecarregados.
Erros comuns incluem objetivos vagos, falta de contexto, critérios de sucesso mal definidos ou mistura de tarefas totalmente distintas em um mesmo texto. O objetivo é passar informação suficiente para o sucesso, mas mantendo foco no resultado claro.
</Accordion>
<Accordion title="Diretrizes para a Saída Esperada" icon="bullseye">
As diretrizes da saída esperada funcionam como contrato entre definição de tarefa e agente, especificando claramente o que deve ser entregue e como será avaliado. Elas abrangem formato, estrutura e elementos essenciais.
As melhores diretrizes incluem exemplos concretos de indicadores de qualidade e critérios claros de conclusão, de modo que agente e revisores humanos possam avaliar o resultado facilmente. Isso reduz ambiguidades e garante resultados consistentes.
Evite descrições genéricas que serviriam para qualquer tarefa, ausência de especificações de formato, padrões vagos ou falta de exemplos/modelos que ajudem o agente a entender as expectativas.
</Accordion>
</AccordionGroup>
### b. Estratégia de Sequenciamento de Tarefas
<Tabs>
<Tab title="Dependências Sequenciais">
Dependências são essenciais quando as tarefas se baseiam em resultados prévios, informações fluem de uma tarefa para outra, ou a qualidade depende da conclusão de fases anteriores. Assim, cada tarefa recebe o contexto correto para o sucesso.
Para implementar bem, use o parâmetro de contexto para encadear tarefas, desenvolvendo gradualmente a complexidade. Cada tarefa deve gerar saídas que alimentam as próximas. O objetivo é manter um fluxo lógico entre as tarefas dependentes, evitando gargalos desnecessários.
Funciona melhor quando há progressão lógica evidente e quando a saída de uma tarefa realmente agrega valor nas etapas seguintes. Cuidado com os gargalos; foque nas dependências essenciais.
</Tab>
<Tab title="Execução Paralela">
A execução paralela é valiosa quando as tarefas são independentes, o tempo é crítico ou há expertise distintas que não exigem coordenação. Pode reduzir drasticamente o tempo total, permitindo que agentes especializados atuem simultaneamente.
Para isso, identifique tarefas realmente independentes, agrupe fluxos de trabalho distintos e planeje a integração dos resultados posteriormente. O ponto-chave é garantir que tarefas paralelas não gerem conflitos ou redundâncias.
Considere o paralelo em múltiplos fluxos independentes, diferentes tipos de análise autônoma, ou criação de conteúdo que pode ser feita ao mesmo tempo. Mas atente-se à alocação de recursos, evitando sobrecarga de modelos ou estouro no orçamento.
</Tab>
</Tabs>
## Otimizando a Configuração dos Agentes para Desempenho de LLMs
### a. Seleção de LLM Guiada pelo Papel
<Warning>
Funções genéricas de agentes tornam impossível escolher o LLM certo. Funções específicas permitem otimização do modelo conforme a função.
</Warning>
A especificidade das funções dos agentes determina quais capacidades de LLM mais importam para alto desempenho, criando oportunidade estratégica de alinhar forças do modelo ao papel do agente.
**Impacto de Funções Genéricas vs. Específicas:**
Ao definir funções, pense no conhecimento do domínio, estilo de trabalho e frameworks decisórios mais valiosos para o tipo de tarefa do agente. Quanto mais específica e contextualizada a função, melhor o modelo incorporará esse papel.
```python
# ✅ Função específica - requisitos claros de LLM
specific_agent = Agent(
role="SaaS Revenue Operations Analyst", # Expertise de domínio clara
goal="Analyze recurring revenue metrics and identify growth opportunities",
backstory="Specialist in SaaS business models with deep understanding of ARR, churn, and expansion revenue",
llm=LLM(model="gpt-4o") # Raciocínio justificado para análise complexa
)
```
**Estratégia de Mapeamento de Função para Modelo:**
- **"Research Analyst"** → Modelo de raciocínio (GPT-4o, Claude Sonnet) para análise complexa
- **"Content Editor"** → Modelo criativo (Claude, GPT-4o) para qualidade de escrita
- **"Data Processor"** → Modelo eficiente (GPT-4o-mini, Gemini Flash) para tarefas estruturadas
- **"API Coordinator"** → Modelo otimizado para function calling (GPT-4o, Claude) para uso de ferramentas
### b. Backstory como Amplificador de Contexto do Modelo
<Info>
Backstories estratégicos maximizam a eficácia do LLM ao contextualizar as respostas de forma que prompts genéricos não conseguem.
</Info>
Um bom backstory transforma a escolha do LLM de genérica a especializada. Isso é crucial para otimizar custos: um modelo eficiente com contexto certo pode superar um premium sem contexto.
**Exemplo de Performance Guiada por Contexto:**
```python
# Contexto amplifica a efetividade do modelo
domain_expert = Agent(
role="B2B SaaS Marketing Strategist",
goal="Develop comprehensive go-to-market strategies for enterprise software",
backstory="""
You have 10+ years of experience scaling B2B SaaS companies from Series A to IPO.
You understand the nuances of enterprise sales cycles, the importance of product-market
fit in different verticals, and how to balance growth metrics with unit economics.
You've worked with companies like Salesforce, HubSpot, and emerging unicorns, giving
you perspective on both established and disruptive go-to-market strategies.
""",
llm=LLM(model="claude-3-5-sonnet", temperature=0.3) # Criatividade balanceada com conhecimento de domínio
)
# Esse contexto faz o Claude agir como especialista do setor
# Sem isso, mesmo ele entregaria respostas genéricas
```
**Elementos de Backstory que Potencializam a Performance de LLMs:**
- **Experiência de Domínio**: "10+ anos em vendas enterprise SaaS"
- **Expertise Específica**: "Especialista em due diligence técnica para Série B+"
- **Estilo de Trabalho**: "Decisões orientadas a dados, documentação clara"
- **Padrões de Qualidade**: "Sempre cita fontes e mostra análise detalhada"
### c. Otimização Holística de Agente + LLM
As configurações mais eficazes criam sinergia entre função específica, profundidade do backstory e escolha do LLM. Cada elemento reforça o outro para maximizar rendimento.
**Framework de Otimização:**
```python
# Exemplo: Agente de Documentação Técnica
tech_writer = Agent(
role="API Documentation Specialist",
goal="Create comprehensive, developer-friendly API documentation",
backstory="""
You're a technical writer with 8+ years documenting REST APIs, GraphQL endpoints,
and SDK integration guides. You've worked with developer tools companies and
understand what developers need: clear examples, comprehensive error handling,
and practical use cases. You prioritize accuracy and usability over marketing fluff.
""",
llm=LLM(
model="claude-3-5-sonnet",
temperature=0.1
),
tools=[code_analyzer_tool, api_scanner_tool],
verbose=True
)
```
**Checklist de Alinhamento:**
- ✅ **Função Específica**: Domínio e responsabilidades claras
- ✅ **Correspondência do LLM**: Forças do modelo conectadas à função
- ✅ **Profundidade do Backstory**: Contexto de domínio disponível pro modelo
- ✅ **Integração de Ferramentas**: Ferramentas fortalecem a função do agente
- ✅ **Ajuste de Parâmetros**: Temperatura e configs otimizadas para a função
O segredo é criar agentes onde cada configuração reforça sua estratégia de escolha do LLM, maximizando rendimento e otimizando custos.
## Checklist Prático de Implementação
Em vez de repetir o framework estratégico, segue um checklist tático para implementar as decisões de seleção de LLM em CrewAI:
<Steps>
<Step title="Audite Sua Configuração Atual" icon="clipboard-check">
**O que analisar:**
- Todos os agentes usam o mesmo LLM por padrão?
- Quais agentes lidam com tarefas mais complexas?
- Quais agentes só processam ou formatam dados?
- Algum agente depende fortemente de ferramentas?
**Ação**: Documente funções dos agentes e identifique oportunidades de otimização.
</Step>
<Step title="Implemente Estratégia no Nível da Crew" icon="users-gear">
**Defina sua Base:**
```python
# Comece com um padrão confiável para a crew
default_crew_llm = LLM(model="gpt-4o-mini") # Base econômica
crew = Crew(
agents=[...],
tasks=[...],
memory=True
)
```
**Ação**: Defina o LLM padrão da crew antes de otimizar agentes individuais.
</Step>
<Step title="Otimize Agentes de Maior Impacto" icon="star">
**Identifique e Aprimore Agentes-Chave:**
```python
# Agentes gerenciadores ou de coordenação
manager_agent = Agent(
role="Project Manager",
llm=LLM(model="gemini-2.5-flash-preview-05-20"),
# ... demais configs
)
# Agentes criativos ou customer-facing
content_agent = Agent(
role="Content Creator",
llm=LLM(model="claude-3-5-sonnet"),
# ... demais configs
)
```
**Ação**: Faça upgrade dos 20% dos agentes que tratam 80% da complexidade.
</Step>
<Step title="Valide com Testes Empresariais" icon="test-tube">
**Após colocar os agentes em produção:**
- Use [CrewAI Enterprise platform](https://app.crewai.com) para testar seleções de modelo A/B
- Execute múltiplas iterações com inputs reais para medir consistência e performance
- Compare custo vs performance na configuração otimizada
- Compartilhe resultados com o time para tomada coletiva de decisão
**Ação**: Substitua achismos por validação com dados reais usando a plataforma de testes.
</Step>
</Steps>
### Quando Usar Tipos Diferentes de Modelos
<Tabs>
<Tab title="Modelos de Raciocínio">
Modelos de raciocínio tornam-se essenciais quando tarefas exigem pensamento lógico genuíno em múltiplas etapas, planejamento estratégico ou decisões complexas beneficiadas por análise sistemática. Brilham na decomposição de problemas e análise estruturada, não no simples seguimento de padrões.
Considere-os para desenvolvimento de estratégias de negócios, análise de dados combinados de múltiplas fontes, resolução de problemas dependente de etapas sucessivas e planejamento estratégico envolvendo múltiplas variáveis.
Entretanto, esses modelos são mais caros e lentos, devendo ser reservados para tarefas onde suas capacidades agregam valor real — evite usá-los apenas para operações simples.
</Tab>
<Tab title="Modelos Criativos">
Modelos criativos são valiosos quando a principal entrega é geração de conteúdo e a qualidade, estilo e engajamento desse conteúdo impactam o sucesso. Se destacam quando redação e estilo importam, ideação criativa é necessária, ou voz de marca é fundamental.
Use-os em redação de posts, criação de artigos, textos de marketing com viés persuasivo, storytelling e comunicações da marca. Costumam captar nuances e contexto melhor do que generalistas.
Podem ser menos adequados para tarefas técnicas ou analíticas, onde precisão supera criatividade. Use-os quando aspectos comunicativos são fatores críticos de sucesso.
</Tab>
<Tab title="Modelos Eficientes">
Modelos eficientes são ideais para operações frequentes e rotineiras, onde velocidade e custo são prioridade. Trabalham melhor em tarefas com parâmetros bem definidos, sem necessidade de raciocínio avançado ou criatividade.
Considere-os para processamento e transformação de dados, formatação simples, chamadas de funções (function calling) e operações em alto volume onde custo importa mais.
O ponto crítico é verificar adequação à tarefa. Funcionam para muitos fluxos rotineiros, mas podem falhar se a tarefa exigir compreensão técnica ou raciocínio.
</Tab>
<Tab title="Modelos Open Source">
Modelos open source são atraentes quando há restrição orçamentária, necessidade de privacidade, personalização especial ou exigência de deployment local.
Considere para ferramentas internas de empresas, aplicações sensíveis, projetos onde não é possível usar APIs externas, casos com orçamento apertado ou requisitos de customização.
Mas lembre-se: exigem mais expertise, manutenção e investimentos em infraestrutura. Avalie o custo total da operação ao avaliar esses modelos.
</Tab>
</Tabs>
## Armadilhas Comuns na Seleção de Modelos CrewAI
<AccordionGroup>
<Accordion title="A Armadilha do 'Um Modelo Serve para Tudo'" icon="triangle-exclamation">
**O problema**: Usar o mesmo LLM para todos os agentes, independentemente das funções. Prática padrão, mas raramente ótima.
**Exemplo real**: Usar GPT-4o tanto para planejamento estratégico quanto para extração simples de dados. O manager precisa do raciocínio premium, mas o extrator poderia usar o GPT-4o-mini, muito mais barato.
**Solução CrewAI**: Configure modelos específicos por agente:
```python
# Agente estratégico recebe modelo premium
manager = Agent(role="Strategy Manager", llm=LLM(model="gpt-4o"))
# Agente de processamento recebe modelo eficiente
processor = Agent(role="Data Processor", llm=LLM(model="gpt-4o-mini"))
```
</Accordion>
<Accordion title="Ignorar Hierarquia de LLM entre Crew e Agente" icon="shuffle">
**O problema**: Não entender como funciona a hierarquia LLM da CrewAI — configurações conflitam entre crew, manager e agentes.
**Exemplo real**: Configurar crew com Claude, mas agentes com GPT, gerando comportamento inconsistente e trocas desnecessárias.
**Solução CrewAI**: Planeje a hierarquia estrategicamente:
```python
crew = Crew(
agents=[agent1, agent2],
tasks=[task1, task2],
manager_llm=LLM(model="gpt-4o"),
process=Process.hierarchical
)
# Agentes herdam o LLM da crew, salvo sobrescrita
agent1 = Agent(llm=LLM(model="claude-3-5-sonnet"))
```
</Accordion>
<Accordion title="Incompatibilidade para Function Calling" icon="screwdriver-wrench">
**O problema**: Escolher modelos pela capacidade geral e ignorar o desempenho em function calling em workflows intensivos em ferramentas.
**Exemplo real**: Selecionar modelo criativo para agente que só precisa chamar APIs e processar dados estruturados, resultando em má extração de parâmetros.
**Solução CrewAI**: Priorize desempenho em function calling para agentes que usam ferramentas:
```python
# Para agentes com muitas ferramentas
tool_agent = Agent(
role="API Integration Specialist",
tools=[search_tool, api_tool, data_tool],
llm=LLM(model="gpt-4o"),
# OU
llm=LLM(model="claude-3-5-sonnet")
)
```
</Accordion>
<Accordion title="Otimização Prematura sem Teste" icon="gear">
**O problema**: Decidir configurações complexas de modelo com base em hipóteses não validadas nos fluxos e tarefas reais CrewAI.
**Exemplo real**: Implementar lógica elaborada de troca de modelo por tipo de tarefa sem testar se os ganhos compensam a complexidade.
**Solução CrewAI**: Comece simples e otimize baseado em dados reais:
```python
# Comece assim
crew = Crew(agents=[...], tasks=[...], llm=LLM(model="gpt-4o-mini"))
# Teste a performance e só depois otimize agentes específicos
# Use testes Enterprise para validar melhorias
```
</Accordion>
<Accordion title="Ignorar Limites de Contexto e Memória" icon="brain">
**O problema**: Não considerar como janela de contexto dos modelos interage com memória e compartilhamento de contexto entre agentes CrewAI.
**Exemplo real**: Usar modelo de contexto curto para agentes que precisam manter histórico ao longo de múltiplas iterações ou equipes com comunicação extensiva agent-to-agent.
**Solução CrewAI**: Alinhe capacidades de contexto ao padrão de comunicação da crew.
</Accordion>
</AccordionGroup>
## Estratégia de Teste e Iteração
<Steps>
<Step title="Comece Simples" icon="play">
Comece com modelos de uso geral, confiáveis e amplamente suportados. Isso estabelece base estável para entender necessidades e expectativas de desempenho antes de otimizar para demandas especializadas.
</Step>
<Step title="Meça o que Importa" icon="chart-line">
Desenvolva métricas alinhadas ao seu caso de uso e metas de negócio, não apenas benchmarks gerais. Foque na mensuração de resultados relevantes ao seu sucesso.
</Step>
<Step title="Itere Baseado em Resultados" icon="arrows-rotate">
Faça mudanças baseadas no desempenho observado no seu contexto, não apenas considerações teóricas ou recomendações genéricas. O desempenho prático costuma ser bem diferente dos benchmarks.
</Step>
<Step title="Considere o Custo Total" icon="calculator">
Avalie todo custo de operação, incluindo modelo, tempo de desenvolvimento, manutenção e complexidade. O modelo mais barato por token pode não ser o mais econômico ao considerar todos os fatores.
</Step>
</Steps>
<Tip>
Foque em entender seus requisitos primeiro, e então escolha modelos que melhor correspondam a essas necessidades. O melhor LLM é aquele que consistentemente entrega os resultados esperados dentro das suas restrições.
</Tip>
### Validação de Modelos em Nível Enterprise
Para equipes sérias sobre otimização, a **plataforma CrewAI Enterprise** oferece testes sofisticados que vão além do CLI. Ela permite avaliação completa para decisões orientadas por dados na estratégia de LLM.
<Frame>
![Enterprise Testing Interface](/images/enterprise/enterprise-testing.png)
</Frame>
**Funcionalidades Avançadas de Teste:**
- **Comparação Multi-Modelo**: Teste diversos LLMs simultaneamente nas mesmas tarefas e entradas. Compare desempenho entre GPT-4o, Claude, Llama, Groq, Cerebras, e outros líderes em paralelo para identificar a melhor opção para você.
- **Rigor Estatístico**: Configure múltiplas iterações com inputs consistentes para medir confiabilidade e variação no desempenho. Assim, identifica modelos que performam bem e de modo consistente.
- **Validação no Mundo Real**: Use os inputs e cenários reais da sua crew, e não apenas benchmarks sintéticos. A plataforma permite testar no contexto da sua indústria, empresa e casos de uso.
- **Analytics Completo**: Acesse métricas detalhadas de desempenho, tempos de execução e análise de custos para todos os modelos testados. Decisões baseadas em dados reais, não apenas reputação.
- **Colaboração em Equipe**: Compartilhe resultados e análises com seu time, favorecendo decisões coletivas e estratégias alinhadas.
Acesse [app.crewai.com](https://app.crewai.com) para começar!
<Info>
A plataforma Enterprise transforma a seleção de modelos de um "palpite" para um processo orientado por dados, permitindo validar os princípios deste guia com seus próprios casos de uso.
</Info>
## Resumo dos Princípios-Chave
<CardGroup cols={2}>
<Card title="Seleção Orientada à Tarefa" icon="bullseye">
Escolha os modelos pelo que sua tarefa realmente requer, não por reputação ou capacidades teóricas.
</Card>
<Card title="Combinação de Capacidades" icon="puzzle-piece">
Alinhe forças do modelo a papéis e responsabilidades dos agentes para melhor desempenho.
</Card>
<Card title="Consistência Estratégica" icon="link">
Mantenha uma estratégia coerente de seleção de modelos em fluxos e componentes relacionados.
</Card>
<Card title="Testes Práticos" icon="flask">
Valide escolhas em uso real, não apenas em benchmarks.
</Card>
<Card title="Iteração Contínua" icon="arrow-up">
Comece simples e otimize com base na performance e necessidade práticas.
</Card>
<Card title="Equilíbrio Operacional" icon="scale-balanced">
Equilibre performance requerida, custo e complexidade.
</Card>
</CardGroup>
<Check>
Lembre-se: o melhor LLM é o que entrega consistentemente os resultados de que você precisa dentro de suas restrições. Conheça seu requisito primeiro, depois selecione o modelo mais adequado.
</Check>
## Panorama Atual dos Modelos (Junho/2025)
<Warning>
**Retrato do Momento**: Os rankings a seguir representam o estado da arte em Junho de 2025, compilados do [LMSys Arena](https://arena.lmsys.org/), [Artificial Analysis](https://artificialanalysis.ai/) e outros benchmarks líderes. Performance, disponibilidade e preço mudam rapidamente. Sempre valide com seus dados e casos reais.
</Warning>
### Principais Modelos por Categoria
As tabelas abaixo mostram uma amostra dos modelos de maior destaque em cada categoria, junto de orientação sobre aplicação em agentes CrewAI:
<Note>
Estas tabelas exibem apenas alguns modelos líderes por categoria. Existem muitos outros excelentes. O objetivo é ilustrar exemplos de capacidades buscadas em vez de apresentar um catálogo completo.
</Note>
<Tabs>
<Tab title="Raciocínio & Planejamento">
**Melhores para LLMs Manager e Análises Complexas**
| Modelo | Score de Inteligência | Custo ($/M tokens) | Velocidade | Melhor Uso em CrewAI |
|:------|:---------------------|:-------------------|:-----------|:--------------------|
| **o3** | 70 | $17.50 | Rápido | Manager LLM para coordenação multi-agente |
| **Gemini 2.5 Pro** | 69 | $3.44 | Rápido | Agentes de planejamento estratégico, coordenação de pesquisa |
| **DeepSeek R1** | 68 | $0.96 | Moderada | Raciocínio com bom custo-benefício |
| **Claude 4 Sonnet** | 53 | $6.00 | Rápido | Agentes de análise que precisam de nuance |
| **Qwen3 235B (Reasoning)** | 62 | $2.63 | Moderada | Alternativa open source para raciocínio |
Esses modelos se destacam em raciocínio multi-etapas e são ideais para agentes que desenvolvem estratégias, coordenam outros agentes ou analisam informações complexas.
</Tab>
<Tab title="Codificação & Técnica">
**Melhores para Desenvolvimento e Workflows com Ferramentas**
| Modelo | Performance em Coding | Tool Use Score | Custo ($/M tokens) | Melhor Uso em CrewAI |
|:--------|:---------------------|:--------------|:-------------------|:--------------------|
| **Claude 4 Sonnet** | Excelente | 72.7% | $6.00 | Agente principal de código/documentação técnica |
| **Claude 4 Opus** | Excelente | 72.5% | $30.00 | Arquitetura complexa, code review |
| **DeepSeek V3** | Muito bom | Alto | $0.48 | Coding econômico para desenvolvimentos rotineiros |
| **Qwen2.5 Coder 32B** | Muito bom | Médio | $0.15 | Agente de código econômico |
| **Llama 3.1 405B** | Bom | 81.1% | $3.50 | LLM para function calling em workflows intensivos em ferramentas |
Otimizados para geração de código, debugging e solução técnica, ideais para equipes de desenvolvimento.
</Tab>
<Tab title="Velocidade & Eficiência">
**Melhores para Operações em Massa e Aplicações em Tempo Real**
| Modelo | Velocidade (tokens/s) | Latência (TTFT) | Custo ($/M tokens) | Melhor Uso em CrewAI |
|:-------|:---------------------|:----------------|:-------------------|:---------------------|
| **Llama 4 Scout** | 2.600 | 0.33s | $0.27 | Agentes de processamento de alto volume |
| **Gemini 2.5 Flash** | 376 | 0.30s | $0.26 | Agentes de resposta em tempo real |
| **DeepSeek R1 Distill** | 383 | Variável | $0.04 | Processamento rápido de baixo custo |
| **Llama 3.3 70B** | 2.500 | 0.52s | $0.60 | Equilíbrio entre velocidade e capacidade |
| **Nova Micro** | Alto | 0.30s | $0.04 | Execução rápida de tarefas simples |
Priorizam velocidade e eficiência, perfeitos para agentes em operações de rotina ou resposta ágil. **Dica:** Usar provedores de inference rápidos como Groq potencializa open source como Llama.
</Tab>
<Tab title="Performance Equilibrada">
**Melhores Modelos Coringa para Crews Diversos**
| Modelo | Score Global | Versatilidade | Custo ($/M tokens) | Melhor Uso em CrewAI |
|:------------|:--------------|:-------------|:-------------------|:--------------------|
| **GPT-4.1** | 53 | Excelente | $3.50 | LLM generalista para equipes variadas |
| **Claude 3.7 Sonnet** | 48 | Muito boa | $6.00 | Raciocínio e criatividade balanceados |
| **Gemini 2.0 Flash** | 48 | Boa | $0.17 | Generalista de bom custo benefício |
| **Llama 4 Maverick** | 51 | Boa | $0.37 | Open source para usos gerais |
| **Qwen3 32B** | 44 | Boa | $1.23 | Versatilidade econômica |
Oferecem bom desempenho geral, adequados para crews com demandas amplas.
</Tab>
</Tabs>
### Framework de Seleção para Modelos Atuais
<AccordionGroup>
<Accordion title="Crews de Alta Performance" icon="rocket">
**Priorizando performance**: Use modelos topo de linha como **o3**, **Gemini 2.5 Pro** ou **Claude 4 Sonnet** para managers e agentes críticos. Excelentes em raciocínio e coordenação, porém mais caros.
**Estratégia**: Implemente abordagem multi-modelo, reservando premium para raciocínio estratégico e eficientes para operações rotineiras.
</Accordion>
<Accordion title="Crews de Baixo Custo" icon="dollar-sign">
**Foco no orçamento**: Foque em modelos como **DeepSeek R1**, **Llama 4 Scout** ou **Gemini 2.0 Flash**, que trazem ótimo desempenho com investimento reduzido.
**Estratégia**: Use modelos econômicos para maioria dos agentes, reservando premium apenas para funções críticas.
</Accordion>
<Accordion title="Workflows Especializados" icon="screwdriver-wrench">
**Para expertise específica**: Escolha modelos otimizados para seu principal caso de uso: **Claude 4** em código, **Gemini 2.5 Pro** em pesquisa, **Llama 405B** em function calling.
**Estratégia**: Selecione conforme a principal função da crew, garantindo alinhamento de capacidade e modelo.
</Accordion>
<Accordion title="Empresa & Privacidade" icon="shield">
**Para operações sensíveis**: Avalie modelos open source como **Llama 4** series, **DeepSeek V3** ou **Qwen3** para deployment privado, mantendo performance competitiva.
**Estratégia**: Use open source em infraestrutura própria e aceite possíveis trade-offs por controle dos dados.
</Accordion>
</AccordionGroup>
### Considerações-Chave na Seleção de Modelos
- **Tendências de Performance**: O cenário atual mostra competição forte entre modelos de raciocínio (o3, Gemini 2.5 Pro) e equilibrados (Claude 4, GPT-4.1). Modelos como DeepSeek R1 entregam excelente custo/performance.
- **Trade-off Velocidade x Inteligência**: Modelos como Llama 4 Scout priorizam velocidade (2.600 tokens/s) e inteligência razoável, enquanto outros como o3 maximizam raciocínio em detrimento de velocidade/preço.
- **Viabilidade Open Source**: A distância entre open source e proprietários diminui a cada mês, com Llama 4 Maverick e DeepSeek V3 entregando performance competitiva a preços atrativos. Inferência rápida via Groq maximiza custo-benefício nesses casos.
<Info>
**Testes são essenciais**: Rankings servem de orientação geral, mas seu caso de uso, prompt e critério podem gerar resultados distintos. Sempre teste modelos candidatos com suas tarefas e dados reais antes de decidir.
</Info>
### Estratégia Prática de Implementação
<Steps>
<Step title="Comece por Modelos Validados">
Inicie com opções consagradas como **GPT-4.1**, **Claude 3.7 Sonnet** ou **Gemini 2.0 Flash**, que oferecem bom desempenho e ampla validação.
</Step>
<Step title="Identifique Demandas Especializadas">
Descubra se sua crew possui requisitos específicos (código, raciocínio, velocidade) que justifiquem modelos como **Claude 4 Sonnet** para desenvolvimento ou **o3** para análise. Para aplicações críticas em velocidade, considere Groq aliado à seleção do modelo.
</Step>
<Step title="Implemente Estratégia Multi-Modelo">
Use modelos diferentes para agentes distintos conforme o papel. Modelos de alta capacidade para managers e tarefas complexas, eficientes para rotinas.
</Step>
<Step title="Monitore e Otimize">
Acompanhe métricas relevantes ao seu caso e esteja pronto para ajustar modelos conforme lançamentos ou mudanças de preços.
</Step>
</Steps>

140
docs/pt-BR/learn/multimodal-agents.mdx Normal file
View File

@@ -0,0 +1,140 @@
---
title: Usando Agentes Multimodais
description: Aprenda como habilitar e usar capacidades multimodais em seus agentes para processar imagens e outros conteúdos não textuais dentro do framework CrewAI.
icon: video
---
## Usando Agentes Multimodais
O CrewAI suporta agentes multimodais que podem processar tanto conteúdo textual quanto não textual, como imagens. Este guia mostrará como habilitar e utilizar capacidades multimodais em seus agentes.
### Habilitando Capacidades Multimodais
Para criar um agente multimodal, basta definir o parâmetro `multimodal` como `True` ao inicializar seu agente:
```python
from crewai import Agent
agent = Agent(
role="Image Analyst",
goal="Analyze and extract insights from images",
backstory="An expert in visual content interpretation with years of experience in image analysis",
multimodal=True # This enables multimodal capabilities
)
```
Ao definir `multimodal=True`, o agente é automaticamente configurado com as ferramentas necessárias para lidar com conteúdo não textual, incluindo a `AddImageTool`.
### Trabalhando com Imagens
O agente multimodal vem pré-configurado com a `AddImageTool`, permitindo que ele processe imagens. Não é necessário adicionar esta ferramenta manualmente – ela é automaticamente incluída ao habilitar capacidades multimodais.
Aqui está um exemplo completo mostrando como usar um agente multimodal para analisar uma imagem:
```python
from crewai import Agent, Task, Crew
# Create a multimodal agent
image_analyst = Agent(
role="Product Analyst",
goal="Analyze product images and provide detailed descriptions",
backstory="Expert in visual product analysis with deep knowledge of design and features",
multimodal=True
)
# Create a task for image analysis
task = Task(
description="Analyze the product image at https://example.com/product.jpg and provide a detailed description",
expected_output="A detailed description of the product image",
agent=image_analyst
)
# Create and run the crew
crew = Crew(
agents=[image_analyst],
tasks=[task]
)
result = crew.kickoff()
```
### Uso Avançado com Contexto
Você pode fornecer contexto adicional ou perguntas específicas sobre a imagem ao criar tarefas para agentes multimodais. A descrição da tarefa pode incluir aspectos específicos nos quais você deseja que o agente foque:
```python
from crewai import Agent, Task, Crew
# Create a multimodal agent for detailed analysis
expert_analyst = Agent(
role="Visual Quality Inspector",
goal="Perform detailed quality analysis of product images",
backstory="Senior quality control expert with expertise in visual inspection",
multimodal=True # AddImageTool is automatically included
)
# Create a task with specific analysis requirements
inspection_task = Task(
description="""
Analyze the product image at https://example.com/product.jpg with focus on:
1. Quality of materials
2. Manufacturing defects
3. Compliance with standards
Provide a detailed report highlighting any issues found.
""",
expected_output="A detailed report highlighting any issues found",
agent=expert_analyst
)
# Create and run the crew
crew = Crew(
agents=[expert_analyst],
tasks=[inspection_task]
)
result = crew.kickoff()
```
### Detalhes da Ferramenta
Ao trabalhar com agentes multimodais, a `AddImageTool` é automaticamente configurada com o seguinte esquema:
```python
class AddImageToolSchema:
image_url: str # Required: The URL or path of the image to process
action: Optional[str] = None # Optional: Additional context or specific questions about the image
```
O agente multimodal irá automaticamente realizar o processamento de imagens por meio de suas ferramentas internas, permitindo que ele:
- Acesse imagens via URLs ou caminhos de arquivos locais
- Processe o conteúdo da imagem com contexto opcional ou perguntas específicas
- Forneça análises e insights com base nas informações visuais e requisitos da tarefa
### Boas Práticas
Ao trabalhar com agentes multimodais, tenha em mente as seguintes boas práticas:
1. **Acesso à Imagem**
- Certifique-se de que suas imagens estejam acessíveis via URLs alcançáveis pelo agente
- Para imagens locais, considere hospedá-las temporariamente ou utilize caminhos absolutos
- Verifique se as URLs das imagens são válidas e acessíveis antes de rodar as tarefas
2. **Descrição da Tarefa**
- Seja específico sobre quais aspectos da imagem você deseja que o agente analise
- Inclua perguntas ou requisitos claros na descrição da tarefa
- Considere usar o parâmetro opcional `action` para uma análise focada
3. **Gerenciamento de Recursos**
- O processamento de imagens pode exigir mais recursos computacionais do que tarefas apenas textuais
- Alguns modelos de linguagem podem exigir codificação em base64 para dados de imagem
- Considere o processamento em lote para múltiplas imagens visando otimizar o desempenho
4. **Configuração do Ambiente**
- Verifique se seu ambiente possui as dependências necessárias para processamento de imagens
- Certifique-se de que seu modelo de linguagem suporta capacidades multimodais
- Teste primeiro com imagens pequenas para validar sua configuração
5. **Tratamento de Erros**
- Implemente tratamento apropriado para falhas no carregamento de imagens
- Tenha estratégias de contingência para casos onde o processamento de imagens falhar
- Monitore e registre operações de processamento de imagens para depuração

158
docs/pt-BR/learn/overview.mdx Normal file
View File

@@ -0,0 +1,158 @@
---
title: "Visão Geral"
description: "Aprenda como construir, personalizar e otimizar suas aplicações CrewAI com guias e tutoriais completos"
icon: "face-smile"
---
## Aprenda CrewAI
Esta seção fornece guias e tutoriais completos para ajudar você a dominar o CrewAI, desde conceitos básicos até técnicas avançadas. Seja você iniciante ou esteja buscando otimizar suas implementações existentes, estes recursos o guiarão por todos os aspectos da construção de workflows poderosos de agentes de IA.
## Guias de Introdução
### Conceitos Centrais
<CardGroup cols={2}>
<Card title="Processo Sequencial" icon="list-ol" href="/pt-BR/learn/sequential-process">
Aprenda a executar tarefas em ordem sequencial para workflows estruturados.
</Card>
<Card title="Processo Hierárquico" icon="sitemap" href="/pt-BR/learn/hierarchical-process">
Implemente execução hierárquica de tarefas com agentes gerentes supervisionando workflows.
</Card>
<Card title="Tarefas Condicionais" icon="code-branch" href="/pt-BR/learn/conditional-tasks">
Crie workflows dinâmicos com execução condicional de tarefas baseada em resultados.
</Card>
<Card title="Kickoff Assíncrono" icon="bolt" href="/pt-BR/learn/kickoff-async">
Execute crews de forma assíncrona para melhorar desempenho e concorrência.
</Card>
</CardGroup>
### Desenvolvimento de Agentes
<CardGroup cols={2}>
<Card title="Personalizando Agentes" icon="user-gear" href="/pt-BR/learn/customizing-agents">
Aprenda como personalizar o comportamento, funções e capacidades dos agentes.
</Card>
<Card title="Codificando Agentes" icon="code" href="/pt-BR/learn/coding-agents">
Construa agentes que podem escrever, executar e depurar código automaticamente.
</Card>
<Card title="Agentes Multimodais" icon="images" href="/pt-BR/learn/multimodal-agents">
Crie agentes capazes de processar texto, imagens e outros tipos de mídia.
</Card>
<Card title="Agente Gerente Personalizado" icon="user-tie" href="/pt-BR/learn/custom-manager-agent">
Implemente agentes gerentes personalizados para workflows hierárquicos complexos.
</Card>
</CardGroup>
## Funcionalidades Avançadas
### Controle de Workflow
<CardGroup cols={2}>
<Card title="Humano no Loop" icon="user-check" href="/pt-BR/learn/human-in-the-loop">
Integre supervisão e intervenção humana aos workflows dos agentes.
</Card>
<Card title="Entrada Humana na Execução" icon="hand-paper" href="/pt-BR/learn/human-input-on-execution">
Permita entrada humana durante a execução de tarefas para tomada de decisões dinâmicas.
</Card>
<Card title="Repetir Tarefas" icon="rotate-left" href="/pt-BR/learn/replay-tasks-from-latest-crew-kickoff">
Refaça e retome tarefas a partir de execuções anteriores de crews.
</Card>
<Card title="Kickoff para Cada" icon="repeat" href="/pt-BR/learn/kickoff-for-each">
Execute crews múltiplas vezes com diferentes entradas de maneira eficiente.
</Card>
</CardGroup>
### Personalização & Integração
<CardGroup cols={2}>
<Card title="LLM Personalizado" icon="brain" href="/pt-BR/learn/custom-llm">
Integre modelos de linguagem personalizados e provedores ao CrewAI.
</Card>
<Card title="Conexões LLM" icon="link" href="/pt-BR/learn/llm-connections">
Configure e gerencie conexões com vários provedores de LLM.
</Card>
<Card title="Criar Ferramentas Personalizadas" icon="wrench" href="/pt-BR/learn/create-custom-tools">
Construa ferramentas personalizadas para estender as capacidades dos agentes.
</Card>
<Card title="Usando Anotações" icon="at" href="/pt-BR/learn/using-annotations">
Use anotações Python para um código mais limpo e fácil de manter.
</Card>
</CardGroup>
## Aplicações Especializadas
### Conteúdo & Mídia
<CardGroup cols={2}>
<Card title="Geração de Imagens DALL-E" icon="image" href="/pt-BR/learn/dalle-image-generation">
Gere imagens utilizando a integração DALL-E com seus agentes.
</Card>
<Card title="Traga Seu Próprio Agente" icon="user-plus" href="/pt-BR/learn/bring-your-own-agent">
Integre agentes e modelos já existentes aos workflows do CrewAI.
</Card>
</CardGroup>
### Gerenciamento de Ferramentas
<CardGroup cols={2}>
<Card title="Forçar Saída da Ferramenta como Resultado" icon="hammer" href="/pt-BR/learn/force-tool-output-as-result">
Configure ferramentas para retornarem sua saída diretamente como resultado da tarefa.
</Card>
</CardGroup>
## Recomendações de Rotas de Aprendizagem
### Para Iniciantes
1. Comece pelo **Processo Sequencial** para entender a execução básica de workflows
2. Aprenda **Personalizando Agentes** para criar configurações de agentes eficazes
3. Explore **Criar Ferramentas Personalizadas** para estender funcionalidades
4. Experimente **Humano no Loop** para workflows interativos
### Para Usuários Intermediários
1. Domine **Processo Hierárquico** para sistemas multiagente complexos
2. Implemente **Tarefas Condicionais** para workflows dinâmicos
3. Utilize **Kickoff Assíncrono** para otimizar desempenho
4. Integre **LLM Personalizado** para modelos especializados
### Para Usuários Avançados
1. Construa **Agentes Multimodais** para processamento complexo de mídias
2. Crie **Agentes Gerentes Personalizados** para orquestração sofisticada
3. Implemente **Traga Seu Próprio Agente** para sistemas híbridos
4. Use **Repetir Tarefas** para recuperação de erros robusta
## Melhores Práticas
### Desenvolvimento
- **Comece Simples**: Inicie com workflows sequenciais básicos antes de adicionar complexidade
- **Teste de Forma Incremental**: Teste cada componente antes de integrar em sistemas maiores
- **Use Anotações**: Aproveite as anotações Python para código mais limpo e sustentável
- **Ferramentas Personalizadas**: Crie ferramentas reutilizáveis que possam ser compartilhadas entre diferentes agentes
### Produção
- **Tratamento de Erros**: Implemente mecanismos robustos de tratamento e recuperação de erros
- **Desempenho**: Utilize execução assíncrona e otimize chamadas a LLM para melhor desempenho
- **Monitoramento**: Integre ferramentas de observabilidade para acompanhar o desempenho dos agentes
- **Supervisão Humana**: Inclua checkpoints humanos para decisões críticas
### Otimização
- **Gestão de Recursos**: Monitore e otimize o uso de tokens e custos de API
- **Design de Workflow**: Elabore workflows que minimizem chamadas desnecessárias ao LLM
- **Eficiência das Ferramentas**: Crie ferramentas eficientes que ofereçam máximo valor com o mínimo de overhead
- **Aprimoramento Iterativo**: Use feedback e métricas para melhorar continuamente o desempenho dos agentes
## Obtendo Ajuda
- **Documentação**: Cada guia inclui exemplos detalhados e explicações
- **Comunidade**: Participe do [Fórum CrewAI](https://community.crewai.com) para discussões e suporte
- **Exemplos**: Consulte a seção de Exemplos para implementações completas e funcionais
- **Suporte**: Entre em contato via [support@crewai.com](mailto:support@crewai.com) para assistência técnica
Comece pelos guias que atendem às suas necessidades atuais e, gradualmente, explore tópicos mais avançados conforme você se sentir confortável com os fundamentos.

78
docs/pt-BR/learn/replay-tasks-from-latest-crew-kickoff.mdx Normal file
View File

@@ -0,0 +1,78 @@
---
title: Reexecutar Tarefas a partir do Último Crew Kickoff
description: Reexecute tarefas a partir do último crew.kickoff(...)
icon: arrow-right
---
## Introdução
O CrewAI oferece a capacidade de reexecutar uma tarefa especificada a partir do último crew kickoff. Esse recurso é particularmente útil quando você concluiu um kickoff e deseja tentar novamente determinadas tarefas, ou não precisa buscar dados novamente porque seus agentes já possuem o contexto salvo da execução do kickoff, sendo necessário apenas reexecutar as tarefas desejadas.
<Note>
Você deve executar `crew.kickoff()` antes de poder reexecutar uma tarefa.
Atualmente, apenas o kickoff mais recente é suportado, então se você utilizar `kickoff_for_each`, será possível reexecutar apenas a partir da execução de crew mais recente.
</Note>
Aqui está um exemplo de como reexecutar a partir de uma tarefa:
### Reexecutando a partir de uma Tarefa Específica Usando o CLI
Para utilizar o recurso de reexecução, siga estes passos:
<Steps>
<Step title="Abra seu terminal ou prompt de comando."></Step>
<Step title="Navegue até o diretório onde está localizado seu projeto CrewAI."></Step>
<Step title="Execute os seguintes comandos:">
Para visualizar os task_ids do último kickoff, utilize:
```shell
crewai log-tasks-outputs
```
Após identificar o `task_id` que deseja reexecutar, utilize:
```shell
crewai replay -t <task_id>
```
</Step>
</Steps>
<Note>
Certifique-se de que o `crewai` está instalado e devidamente configurado no seu ambiente de desenvolvimento.
</Note>
### Reexecutando uma Tarefa Programaticamente
Para reexecutar uma tarefa programaticamente, siga os passos abaixo:
<Steps>
<Step title="Especifique o `task_id` e os parâmetros de entrada para o processo de reexecução.">
Especifique o `task_id` e os parâmetros de entrada para o processo de reexecução.
</Step>
<Step title="Execute o comando de reexecução dentro de um bloco try-except para lidar com possíveis erros.">
Execute o comando de reexecução dentro de um bloco try-except para lidar com possíveis erros.
<CodeGroup>
```python Code
def replay():
"""
Replay the crew execution from a specific task.
"""
task_id = '<task_id>'
inputs = {"topic": "CrewAI Training"} # This is optional; you can pass in the inputs you want to replay; otherwise, it uses the previous kickoff's inputs.
try:
YourCrewName_Crew().crew().replay(task_id=task_id, inputs=inputs)
except subprocess.CalledProcessError as e:
raise Exception(f"An error occurred while replaying the crew: {e}")
except Exception as e:
raise Exception(f"An unexpected error occurred: {e}")
```
</CodeGroup>
</Step>
</Steps>
## Conclusão
Com as melhorias acima e funcionalidades detalhadas, a reexecução de tarefas específicas no CrewAI ficou mais eficiente e robusta.
Certifique-se de seguir exatamente os comandos e passos para aproveitar ao máximo esses recursos.

127
docs/pt-BR/learn/sequential-process.mdx Normal file
View File

@@ -0,0 +1,127 @@
---
title: Processos Sequenciais
description: Um guia abrangente para utilizar os processos sequenciais na execução de tarefas em projetos CrewAI.
icon: forward
---
## Introdução
O CrewAI oferece uma estrutura flexível para execução de tarefas de maneira estruturada, suportando tanto processos sequenciais quanto hierárquicos.
Este guia descreve como implementar esses processos de forma eficaz para garantir execução eficiente das tarefas e a conclusão do projeto.
## Visão Geral do Processo Sequencial
O processo sequencial garante que as tarefas sejam executadas uma após a outra, seguindo um progresso linear.
Essa abordagem é ideal para projetos nos quais as tarefas precisam ser concluídas em uma ordem específica.
### Principais Características
- **Fluxo Linear de Tarefas**: Garante o progresso ordenado ao tratar tarefas em uma sequência pré-determinada.
- **Simplicidade**: Melhor opção para projetos com tarefas claras e passo a passo.
- **Fácil Monitoramento**: Facilita o acompanhamento da conclusão das tarefas e do progresso do projeto.
## Implementando o Processo Sequencial
Para utilizar o processo sequencial, monte sua crew e defina as tarefas na ordem em que devem ser executadas.
```python Code
from crewai import Crew, Process, Agent, Task, TaskOutput, CrewOutput
# Define your agents
researcher = Agent(
role='Researcher',
goal='Conduct foundational research',
backstory='An experienced researcher with a passion for uncovering insights'
)
analyst = Agent(
role='Data Analyst',
goal='Analyze research findings',
backstory='A meticulous analyst with a knack for uncovering patterns'
)
writer = Agent(
role='Writer',
goal='Draft the final report',
backstory='A skilled writer with a talent for crafting compelling narratives'
)
# Define your tasks
research_task = Task(
description='Gather relevant data...',
agent=researcher,
expected_output='Raw Data'
)
analysis_task = Task(
description='Analyze the data...',
agent=analyst,
expected_output='Data Insights'
)
writing_task = Task(
description='Compose the report...',
agent=writer,
expected_output='Final Report'
)
# Form the crew with a sequential process
report_crew = Crew(
agents=[researcher, analyst, writer],
tasks=[research_task, analysis_task, writing_task],
process=Process.sequential
)
# Execute the crew
result = report_crew.kickoff()
# Accessing the type-safe output
task_output: TaskOutput = result.tasks[0].output
crew_output: CrewOutput = result.output
```
### Nota:
Cada tarefa em um processo sequencial **deve** ter um agente atribuído. Certifique-se de que todo `Task` inclua um parâmetro `agent`.
### Fluxo de Trabalho em Ação
1. **Tarefa Inicial**: Em um processo sequencial, o primeiro agente conclui sua tarefa e sinaliza a finalização.
2. **Tarefas Subsequentes**: Os agentes assumem suas tarefas conforme o tipo de processo, com os resultados das tarefas anteriores ou diretrizes orientando sua execução.
3. **Finalização**: O processo é concluído assim que a última tarefa é executada, levando à conclusão do projeto.
## Funcionalidades Avançadas
### Delegação de Tarefas
Em processos sequenciais, se um agente possui `allow_delegation` definido como `True`, ele pode delegar tarefas para outros agentes na crew.
Esse recurso é configurado automaticamente quando há múltiplos agentes na crew.
### Execução Assíncrona
As tarefas podem ser executadas de forma assíncrona, permitindo processamento paralelo quando apropriado.
Para criar uma tarefa assíncrona, defina `async_execution=True` ao criar a tarefa.
### Memória e Cache
O CrewAI suporta recursos de memória e cache:
- **Memória**: Habilite definindo `memory=True` ao criar a Crew. Isso permite aos agentes reter informações entre as tarefas.
- **Cache**: Por padrão, o cache está habilitado. Defina `cache=False` para desativá-lo.
### Callbacks
Você pode definir callbacks tanto no nível da tarefa quanto no nível de etapa:
- `task_callback`: Executado após a conclusão de cada tarefa.
- `step_callback`: Executado após cada etapa na execução de um agente.
### Métricas de Uso
O CrewAI rastreia o uso de tokens em todas as tarefas e agentes. Você pode acessar essas métricas após a execução.
## Melhores Práticas para Processos Sequenciais
1. **A Ordem Importa**: Organize as tarefas em uma sequência lógica, onde cada uma aproveite o resultado da anterior.
2. **Descrições Claras de Tarefas**: Forneça descrições detalhadas para cada tarefa, orientando os agentes de forma eficaz.
3. **Seleção Apropriada de Agentes**: Relacione as habilidades e funções dos agentes às necessidades de cada tarefa.
4. **Use o Contexto**: Aproveite o contexto das tarefas anteriores para informar as seguintes.
Esta documentação atualizada garante que os detalhes reflitam com precisão as últimas mudanças no código e descreve claramente como aproveitar novos recursos e configurações.
O conteúdo foi mantido simples e direto para garantir fácil compreensão.

141
docs/pt-BR/learn/using-annotations.mdx Normal file
View File

@@ -0,0 +1,141 @@
---
title: "Usando Anotações no crew.py"
description: "Aprenda como usar anotações para estruturar corretamente agentes, tarefas e componentes no CrewAI"
icon: "at"
---
Este guia explica como utilizar anotações para referenciar corretamente **agentes**, **tarefas** e outros componentes no arquivo `crew.py`.
## Introdução
As anotações no framework CrewAI são utilizadas para decorar classes e métodos, fornecendo metadados e funcionalidades para diversos componentes do seu crew. Essas anotações auxiliam na organização e estruturação do seu código, tornando-o mais legível e fácil de manter.
## Anotações Disponíveis
O framework CrewAI fornece as seguintes anotações:
- `@CrewBase`: Usada para decorar a classe principal do crew.
- `@agent`: Decora métodos que definem e retornam objetos Agent.
- `@task`: Decora métodos que definem e retornam objetos Task.
- `@crew`: Decora o método que cria e retorna o objeto Crew.
- `@llm`: Decora métodos que inicializam e retornam objetos Language Model.
- `@tool`: Decora métodos que inicializam e retornam objetos Tool.
- `@callback`: Utilizada para definir métodos de callback.
- `@output_json`: Utilizada para métodos que retornam dados em JSON.
- `@output_pydantic`: Utilizada para métodos que retornam modelos Pydantic.
- `@cache_handler`: Utilizada para definição de métodos de manipulação de cache.
## Exemplos de Uso
Vamos passar por exemplos de como utilizar essas anotações:
### 1. Classe Base do Crew
```python
@CrewBase
class LinkedinProfileCrew():
"""LinkedinProfile crew"""
agents_config = 'config/agents.yaml'
tasks_config = 'config/tasks.yaml'
```
A anotação `@CrewBase` é usada para decorar a classe principal do crew. Esta classe geralmente contém as configurações e métodos para criação de agentes, tarefas e do próprio crew.
### 2. Definição de Tool
```python
@tool
def myLinkedInProfileTool(self):
return LinkedInProfileTool()
```
A anotação `@tool` é usada para decorar métodos que retornam objetos tool. Essas ferramentas podem ser usadas por agentes para executar tarefas específicas.
### 3. Definição de LLM
```python
@llm
def groq_llm(self):
api_key = os.getenv('api_key')
return ChatGroq(api_key=api_key, temperature=0, model_name="mixtral-8x7b-32768")
```
A anotação `@llm` é usada para decorar métodos que inicializam e retornam objetos Language Model. Esses LLMs são utilizados pelos agentes para tarefas de processamento de linguagem natural.
### 4. Definição de Agente
```python
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher']
)
```
A anotação `@agent` é usada para decorar métodos que definem e retornam objetos Agent.
### 5. Definição de Tarefa
```python
@task
def research_task(self) -> Task:
return Task(
config=self.tasks_config['research_linkedin_task'],
agent=self.researcher()
)
```
A anotação `@task` é usada para decorar métodos que definem e retornam objetos Task. Esses métodos especificam a configuração da tarefa e o agente responsável por ela.
### 6. Criação do Crew
```python
@crew
def crew(self) -> Crew:
"""Creates the LinkedinProfile crew"""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True
)
```
A anotação `@crew` é usada para decorar o método que cria e retorna o objeto `Crew`. Este método reúne todos os componentes (agentes e tarefas) em um crew funcional.
## Configuração YAML
As configurações dos agentes geralmente são armazenadas em um arquivo YAML. Veja um exemplo de como o arquivo `agents.yaml` pode ser estruturado para o agente researcher:
```yaml
researcher:
role: >
LinkedIn Profile Senior Data Researcher
goal: >
Uncover detailed LinkedIn profiles based on provided name {name} and domain {domain}
Generate a Dall-E image based on domain {domain}
backstory: >
You're a seasoned researcher with a knack for uncovering the most relevant LinkedIn profiles.
Known for your ability to navigate LinkedIn efficiently, you excel at gathering and presenting
professional information clearly and concisely.
allow_delegation: False
verbose: True
llm: groq_llm
tools:
- myLinkedInProfileTool
- mySerperDevTool
- myDallETool
```
Esta configuração YAML corresponde ao agente researcher definido na classe `LinkedinProfileCrew`. A configuração especifica o papel do agente, objetivo, contexto e outras propriedades, como o LLM e as tools que ele utiliza.
Repare como os campos `llm` e `tools` no arquivo YAML correspondem aos métodos decorados com `@llm` e `@tool` na classe Python.
## Boas Práticas
- **Nomenclatura Consistente**: Utilize nomenclatura clara e consistente para seus métodos. Por exemplo, métodos de agentes podem ser nomeados de acordo com suas funções (ex: researcher, reporting_analyst).
- **Variáveis de Ambiente**: Utilize variáveis de ambiente para informações sensíveis como chaves de API.
- **Flexibilidade**: Estruture seu crew de forma flexível, permitindo fácil adição ou remoção de agentes e tarefas.
- **Correspondência YAML-Código**: Assegure que os nomes e estruturas nos arquivos YAML correspondam corretamente aos métodos decorados em seu código Python.
Seguindo essas orientações e utilizando corretamente as anotações, você conseguirá criar crews bem estruturados e de fácil manutenção utilizando o framework CrewAI.

64
docs/pt-BR/mcp/multiple-servers.mdx Normal file
View File

@@ -0,0 +1,64 @@
---
title: Conectando a Múltiplos Servidores MCP
description: Saiba como usar o MCPServerAdapter no CrewAI para conectar-se simultaneamente a múltiplos servidores MCP e agregar suas ferramentas.
icon: layer-group
---
## Visão Geral
O `MCPServerAdapter` em `crewai-tools` permite que você conecte-se a vários servidores MCP simultaneamente. Isso é útil quando seus agentes precisam acessar ferramentas distribuídas entre diferentes serviços ou ambientes. O adaptador agrega as ferramentas de todos os servidores especificados, tornando-as disponíveis para seus agentes CrewAI.
## Configuração
Para conectar-se a múltiplos servidores, você fornece uma lista de dicionários de parâmetros de servidor para o `MCPServerAdapter`. Cada dicionário na lista deve definir os parâmetros para um servidor MCP.
Os tipos de transporte suportados para cada servidor na lista incluem `stdio`, `sse` e `streamable-http`.
```python
from crewai import Agent, Task, Crew, Process
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters # Needed for Stdio example
# Define parameters for multiple MCP servers
server_params_list = [
# Streamable HTTP Server
{
"url": "http://localhost:8001/mcp",
"transport": "streamable-http"
},
# SSE Server
{
"url": "http://localhost:8000/sse",
"transport": "sse"
},
# StdIO Server
StdioServerParameters(
command="python3",
args=["servers/your_stdio_server.py"],
env={"UV_PYTHON": "3.12", **os.environ},
)
]
try:
with MCPServerAdapter(server_params_list) as aggregated_tools:
print(f"Available aggregated tools: {[tool.name for tool in aggregated_tools]}")
multi_server_agent = Agent(
role="Versatile Assistant",
goal="Utilize tools from local Stdio, remote SSE, and remote HTTP MCP servers.",
backstory="An AI agent capable of leveraging a diverse set of tools from multiple sources.",
tools=aggregated_tools, # All tools are available here
verbose=True,
)
... # Your other agent, tasks, and crew code here
except Exception as e:
print(f"Error connecting to or using multiple MCP servers (Managed): {e}")
print("Ensure all MCP servers are running and accessible with correct configurations.")
```
## Gerenciamento de Conexão
Ao utilizar o gerenciador de contexto (`with` statement), o `MCPServerAdapter` gerencia o ciclo de vida (início e término) de todas as conexões aos servidores MCP configurados. Isso simplifica o gerenciamento de recursos e garante que todas as conexões sejam devidamente fechadas ao sair do contexto.

215
docs/pt-BR/mcp/overview.mdx Normal file
View File

@@ -0,0 +1,215 @@
---
title: 'Servidores MCP como Ferramentas no CrewAI'
description: 'Aprenda como integrar servidores MCP como ferramentas nos seus agentes CrewAI usando a biblioteca `crewai-tools`.'
icon: plug
---
## Visão Geral
O [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) fornece uma maneira padronizada para agentes de IA fornecerem contexto para LLMs comunicando-se com serviços externos, conhecidos como Servidores MCP.
A biblioteca `crewai-tools` expande as capacidades do CrewAI permitindo que você integre facilmente ferramentas desses servidores MCP em seus agentes.
Isso oferece às suas crews acesso a um vasto ecossistema de funcionalidades.
Atualmente, suportamos os seguintes mecanismos de transporte:
- **Stdio**: para servidores locais (comunicação via entrada/saída padrão entre processos na mesma máquina)
- **Server-Sent Events (SSE)**: para servidores remotos (transmissão de dados unidirecional em tempo real do servidor para o cliente via HTTP)
- **Streamable HTTP**: para servidores remotos (comunicação flexível e potencialmente bidirecional via HTTP, geralmente utilizando SSE para streams do servidor para o cliente)
## Tutorial em Vídeo
Assista a este tutorial em vídeo para um guia abrangente sobre a integração do MCP com o CrewAI:
<iframe
width="100%"
height="400"
src="https://www.youtube.com/embed/TpQ45lAZh48"
title="CrewAI MCP Integration Guide"
frameborder="0"
style={{ borderRadius: '10px' }}
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
## Instalação
Antes de começar a usar MCP com `crewai-tools`, é necessário instalar a dependência extra `mcp` do `crewai-tools` com o seguinte comando:
```shell
uv pip install 'crewai-tools[mcp]'
```
## Conceitos Chave & Primeiros Passos
A classe `MCPServerAdapter` da `crewai-tools` é a principal forma de conectar-se a um servidor MCP e disponibilizar suas ferramentas aos seus agentes CrewAI. Ela suporta diferentes mecanismos de transporte e simplifica o gerenciamento de conexões.
O uso de um gerenciador de contexto Python (`with`) é a **abordagem recomendada** para o `MCPServerAdapter`. Ele lida automaticamente com a abertura e o fechamento da conexão com o servidor MCP.
```python
from crewai import Agent
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters # Para servidor Stdio
# Exemplo de server_params (escolha um baseado no seu tipo de servidor):
# 1. Servidor Stdio:
server_params=StdioServerParameters(
command="python3",
args=["servers/your_server.py"],
env={"UV_PYTHON": "3.12", **os.environ},
)
# 2. Servidor SSE:
server_params = {
"url": "http://localhost:8000/sse",
"transport": "sse"
}
# 3. Servidor Streamable HTTP:
server_params = {
"url": "http://localhost:8001/mcp",
"transport": "streamable-http"
}
# Exemplo de uso (descomente e adapte após definir server_params):
with MCPServerAdapter(server_params) as mcp_tools:
print(f"Available tools: {[tool.name for tool in mcp_tools]}")
my_agent = Agent(
role="MCP Tool User",
goal="Utilize tools from an MCP server.",
backstory="I can connect to MCP servers and use their tools.",
tools=mcp_tools, # Passe as ferramentas carregadas para o seu agente
reasoning=True,
verbose=True
)
# ... restante da configuração do seu crew ...
```
Este padrão geral mostra como integrar ferramentas. Para exemplos específicos para cada transporte, consulte os guias detalhados abaixo.
## Filtrando Ferramentas
```python
with MCPServerAdapter(server_params) as mcp_tools:
print(f"Available tools: {[tool.name for tool in mcp_tools]}")
my_agent = Agent(
role="MCP Tool User",
goal="Utilize tools from an MCP server.",
backstory="I can connect to MCP servers and use their tools.",
tools=mcp_tools["tool_name"], # Passe as ferramentas filtradas para o seu agente
reasoning=True,
verbose=True
)
# ... restante da configuração do seu crew ...
```
## Usando com CrewBase
Para usar ferramentas de servidores MCP dentro de uma classe CrewBase, utilize o método `mcp_tools`. As configurações dos servidores devem ser fornecidas via o atributo mcp_server_params. Você pode passar uma configuração única ou uma lista com múltiplas configurações.
```python
@CrewBase
class CrewWithMCP:
# ... defina o arquivo de configuração de agentes e tasks ...
mcp_server_params = [
# Servidor Streamable HTTP
{
"url": "http://localhost:8001/mcp",
"transport": "streamable-http"
},
# Servidor SSE
{
"url": "http://localhost:8000/sse",
"transport": "sse"
},
# Servidor StdIO
StdioServerParameters(
command="python3",
args=["servers/your_stdio_server.py"],
env={"UV_PYTHON": "3.12", **os.environ},
)
]
@agent
def your_agent(self):
return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) # você também pode filtrar quais ferramentas estarão disponíveis
# ... restante da configuração do seu crew ...
```
## Explore Integrações MCP
<CardGroup cols={2}>
<Card
title="Transporte Stdio"
icon="server"
href="/pt-BR/mcp/stdio"
color="#3B82F6"
>
Conecte-se a servidores MCP locais via entrada/saída padrão. Ideal para scripts e executáveis locais.
</Card>
<Card
title="Transporte SSE"
icon="wifi"
href="/pt-BR/mcp/sse"
color="#10B981"
>
Integre com servidores MCP remotos usando Server-Sent Events para streaming de dados em tempo real.
</Card>
<Card
title="Transporte HTTP Streamable"
icon="globe"
href="/pt-BR/mcp/streamable-http"
color="#F59E0B"
>
Utilize HTTP Streamable para uma comunicação robusta com servidores MCP remotos.
</Card>
<Card
title="Conectando a Múltiplos Servidores"
icon="layer-group"
href="/pt-BR/mcp/multiple-servers"
color="#8B5CF6"
>
Agregue ferramentas de vários servidores MCP simultaneamente usando um único adaptador.
</Card>
<Card
title="Considerações de Segurança"
icon="lock"
href="/pt-BR/mcp/security"
color="#EF4444"
>
Revise práticas importantes de segurança para integração MCP e mantenha seus agentes protegidos.
</Card>
</CardGroup>
Confira este repositório para demonstrações completas e exemplos de integração MCP com CrewAI! 👇
<Card
title="Repositório GitHub"
icon="github"
href="https://github.com/tonykipkemboi/crewai-mcp-demo"
target="_blank"
>
Demo MCP do CrewAI
</Card>
## Segurança ao Usar MCP
<Warning>
Sempre assegure-se de confiar no servidor MCP antes de utilizá-lo.
</Warning>
#### Aviso de Segurança: Ataques de DNS Rebinding
Transportes SSE podem ser vulneráveis a ataques de DNS rebinding se não forem devidamente protegidos.
Para prevenir isso:
1. **Sempre valide os cabeçalhos Origin** das conexões SSE recebidas para garantir que venham de fontes esperadas
2. **Evite vincular servidores a todas as interfaces de rede** (0.0.0.0) quando executando localmente – faça o bind apenas para localhost (127.0.0.1)
3. **Implemente autenticação adequada** para todas as conexões SSE
Sem essas proteções, invasores podem usar DNS rebinding para interagir com servidores MCP locais via sites remotos.
Para mais detalhes, consulte a [documentação de Segurança de Transporte da MCP da Anthropic](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations).
### Limitações
* **Primitivas Suportadas**: Atualmente, o `MCPServerAdapter` suporta principalmente a adaptação de `tools` MCP.
Outras primitivas MCP como `prompts` ou `resources` não são integradas diretamente como componentes CrewAI através deste adaptador por enquanto.
* **Manipulação de Saída**: O adaptador normalmente processa a saída principal de texto de uma ferramenta MCP (por exemplo, `.content[0].text`). Saídas complexas ou multimodais podem exigir tratamento customizado caso não se encaixem nesse padrão.

165
docs/pt-BR/mcp/security.mdx Normal file
View File

@@ -0,0 +1,165 @@
---
title: Considerações de Segurança MCP
description: Saiba mais sobre as principais melhores práticas de segurança ao integrar servidores MCP com seus agentes CrewAI.
icon: lock
---
## Visão Geral
<Warning>
O aspecto mais crítico da segurança MCP é a **confiança**. Você deve **apenas** conectar seus agentes CrewAI a servidores MCP nos quais confie plenamente.
</Warning>
Ao integrar serviços externos como servidores MCP (Model Context Protocol) aos seus agentes CrewAI, a segurança é fundamental.
Servidores MCP podem executar código, acessar dados ou interagir com outros sistemas com base nas ferramentas que expõem.
É crucial compreender as implicações e seguir as melhores práticas para proteger suas aplicações e dados.
### Riscos
- Executar código arbitrário na máquina onde o agente está rodando (especialmente com o transporte `Stdio` se o servidor puder controlar o comando executado).
- Expor dados sensíveis do seu agente ou do seu ambiente.
- Manipular o comportamento do seu agente de maneiras não intencionais, incluindo realizar chamadas de API não autorizadas em seu nome.
- Sequestrar o processo de raciocínio do agente através de técnicas sofisticadas de prompt injection (veja abaixo).
### 1. Confiando em Servidores MCP
<Warning>
**Somente conecte-se a servidores MCP em que confie.**
</Warning>
Antes de configurar o `MCPServerAdapter` para conectar a um servidor MCP, certifique-se de saber:
- **Quem opera o servidor?** É um serviço conhecido, de reputação confiável, ou um servidor interno sob o seu controle?
- **Quais ferramentas ele expõe?** Entenda as capacidades das ferramentas. Elas poderiam ser mal utilizadas caso um invasor obtenha controle ou se o próprio servidor for malicioso?
- **Quais dados ele acessa ou processa?** Saiba se há informações sensíveis que possam ser enviadas ou manipuladas pelo servidor MCP.
Evite conectar-se a servidores MCP desconhecidos ou não verificados, especialmente se seus agentes lidam com tarefas ou dados sensíveis.
### 2. Prompt Injection Seguro via Metadados de Ferramentas: O Risco do "Model Control Protocol"
Um risco significativo e sutil é o potencial para prompt injection através dos metadados das ferramentas. Veja como funciona:
1. Quando seu agente CrewAI se conecta a um servidor MCP, ele normalmente solicita uma lista de ferramentas disponíveis.
2. O servidor MCP responde com metadados para cada ferramenta, incluindo nome, descrição e descrições de parâmetros.
3. O LLM (Modelo de Linguagem) subjacente do seu agente usa esses metadados para entender como e quando usar as ferramentas. Muitas vezes esses metadados são incorporados no system prompt ou contexto do LLM.
4. Um servidor MCP malicioso pode construir seus metadados (nomes, descrições) para incluir instruções ocultas ou explícitas. Essas instruções podem atuar como prompt injection, efetivamente fazendo o LLM se comportar de determinada maneira, revelar informações sensíveis ou executar ações maliciosas.
**Crucialmente, esse ataque pode ocorrer simplesmente ao conectar-se a um servidor malicioso e listar suas ferramentas, mesmo que seu agente nunca decida *usar* essas ferramentas.** A mera exposição aos metadados maliciosos pode ser suficiente para comprometer o comportamento do agente.
**Mitigação:**
* **Extrema Cautela com Servidores Não Confiáveis:** Reitere: *Não conecte-se a servidores MCP nos quais você não confie totalmente.* O risco de injection de metadados torna isso fundamental.
### Segurança do Transporte Stdio
O transporte Stdio (Entrada/Saída Padrão) é tipicamente usado para servidores MCP locais, rodando na mesma máquina que sua aplicação CrewAI.
- **Isolamento de Processo**: Embora geralmente seja mais seguro pois não envolve exposição de rede por padrão, assegure-se de que o script ou comando executado pelo `StdioServerParameters` é de uma fonte confiável e possui permissões de sistema de arquivos adequadas. Um script Stdio servidor malicioso pode ainda prejudicar seu sistema local.
- **Saneamento de Entrada**: Se o seu script de servidor Stdio recebe entradas complexas derivadas das interações do agente, garanta que o script saneie essas entradas para evitar injection de comandos ou outras vulnerabilidades na lógica do script.
- **Limite de Recursos**: Esteja atento ao fato de que o processo servidor Stdio consome recursos locais (CPU, memória). Assegure-se de que seja bem comportado, evitando esgotar os recursos do sistema.
### Ataques de Confused Deputy
O [Problema do Confused Deputy](https://en.wikipedia.org/wiki/Confused_deputy_problem) é uma vulnerabilidade clássica de segurança que pode se manifestar em integrações MCP, especialmente quando um servidor MCP atua como proxy para outros serviços de terceiros (ex: Google Calendar, GitHub) que usam OAuth 2.0 para autorização.
**Cenário:**
1. Um servidor MCP (vamos chamá-lo de `MCP-Proxy`) permite que seu agente interaja com o `ThirdPartyAPI`.
2. O `MCP-Proxy` usa seu próprio `client_id` estático ao comunicar-se com o servidor de autorização do `ThirdPartyAPI`.
3. Você, como usuário, autoriza legitimamente o `MCP-Proxy` a acessar o `ThirdPartyAPI` em seu nome. Durante esse processo, o servidor de autenticação pode definir um cookie no seu navegador indicando seu consentimento para o `client_id` do `MCP-Proxy`.
4. Um invasor cria um link malicioso. Esse link inicia um fluxo OAuth com o `MCP-Proxy`, mas é projetado para enganar o servidor de autenticação do `ThirdPartyAPI`.
5. Se você clicar nesse link e o servidor de autenticação do `ThirdPartyAPI` encontrar seu cookie de consentimento existente para o `client_id` do `MCP-Proxy`, pode *deixar de* pedir seu consentimento novamente.
6. O `MCP-Proxy` pode, então, ser enganado a encaminhar um código de autorização (para o `ThirdPartyAPI`) para o atacante, ou um código de autorização MCP que o atacante possa usar para se passar por você perante o `MCP-Proxy`.
**Mitigação (Principalmente para Desenvolvedores de Servidores MCP):**
* Servidores proxy MCP usando IDs de cliente estáticos para serviços downstream **devem** obter consentimento explícito do usuário para *cada aplicação cliente ou agente* conectando-se a eles *antes* de iniciar um fluxo OAuth com o serviço de terceiros. Isso significa que o `MCP-Proxy` deve exibir uma tela de consentimento.
**Implicação para Usuários CrewAI:**
* Fique atento se um servidor MCP redireciona você para múltiplas autenticações OAuth, especialmente se isso for inesperado ou se as permissões solicitadas forem muito amplas.
* Prefira servidores MCP que deixem clara sua própria identidade e a identidade dos serviços de terceiros que possam fazer proxy.
### Segurança no Transporte Remoto (SSE & HTTP Transmitível)
Ao conectar-se a servidores MCP remotos via Server-Sent Events (SSE) ou HTTP transmitível, práticas padrão de segurança web são essenciais.
### Considerações de Segurança SSE
### a. Ataques de DNS Rebinding (Especialmente para SSE)
<Critical>
**Proteja-se contra ataques de DNS Rebinding.**
</Critical>
DNS rebinding permite que um site controlado por atacante contorne a política de mesma origem e faça requisições para servidores na rede local do usuário (ex: `localhost`) ou intranet. Isso é particularmente arriscado se você roda um servidor MCP localmente (ex: para desenvolvimento) e um agente em um ambiente do tipo navegador (embora menos comum no backend CrewAI) ou se o servidor MCP está em uma rede interna.
**Estratégias de Mitigação para Implementadores de Servidores MCP:**
- **Valide os Headers `Origin` e `Host`**: Servidores MCP (especialmente com SSE) devem validar os headers HTTP `Origin` e/ou `Host` para garantir que as requisições venham dos domínios/clientes esperados.
- **Ligue em `localhost` (127.0.0.1)**: Ao rodar servidores MCP localmente para desenvolvimento, conecte-se a `127.0.0.1` em vez de `0.0.0.0`. Isso impede que sejam acessíveis por outras máquinas na rede.
- **Autenticação**: Exija autenticação para todas as conexões ao seu servidor MCP caso não seja destinado a acesso público anônimo.
### b. Use HTTPS
- **Criptografe Dados em Trânsito**: Sempre use HTTPS (HTTP Seguro) para URLs de servidores MCP remotos. Isso criptografa a comunicação entre sua aplicação CrewAI e o servidor MCP, protegendo contra escuta e ataques Man-in-the-Middle (MitM). O `MCPServerAdapter` respeitará o esquema (`http` ou `https`) fornecido na URL.
### c. Token Passthrough (Anti-Padrão)
Isso é uma preocupação principalmente para desenvolvedores de servidores MCP, mas entender o conceito ajuda a escolher servidores seguros.
"Token passthrough" é quando um servidor MCP aceita um token de acesso do seu agente CrewAI (que pode ser um token para um serviço *diferente*, por exemplo, `ServiceA`) e simplesmente o repassa para outra API ( `ServiceB`) downstream sem validação adequada. Especificamente, `ServiceB` (ou o próprio servidor MCP) só deveria aceitar tokens explicitamente emitidos *para eles* (ou seja, o claim 'audience' no token deve corresponder ao servidor/serviço).
**Riscos:**
* Burlar controles de segurança (como limites de taxa ou permissões granulares) no servidor MCP ou na API downstream.
* Quebra trilhas de auditoria e responsabilização.
* Permite uso indevido de tokens roubados.
**Mitigação (Para Desenvolvedores de Servidores MCP):**
* Servidores MCP **NÃO DEVEM** aceitar tokens que não foram explicitamente emitidos para eles. Devem validar o claim de audiência dos tokens.
**Implicação para Usuários CrewAI:**
* Embora isso não seja diretamente controlável pelo usuário, destaca a importância de conectar-se a servidores MCP bem projetados e que sigam as melhores práticas de segurança.
#### Autenticação e Autorização
- **Verifique a Identidade**: Se o servidor MCP fornece ferramentas sensíveis ou acesso a dados privados, ele DEVE implementar mecanismos de autenticação robustos para verificar a identidade do cliente (sua aplicação CrewAI). Isso pode envolver chaves de API, tokens OAuth ou outros métodos padrão.
- **Princípio do Menor Privilégio**: Certifique-se de que as credenciais usadas pelo `MCPServerAdapter` (se houver) tenham apenas as permissões necessárias para acessar as ferramentas requeridas.
### d. Validação e Saneamento de Entrada
- **Validação de Entrada é Crítica**: Servidores MCP **devem** validar rigorosamente todas as entradas recebidas de agentes *antes* de processá-las ou passá-las para as ferramentas. Esta é a principal defesa contra diversas vulnerabilidades comuns:
- **Injection de Comando:** Caso uma ferramenta construa comandos de shell, queries SQL ou outras instruções de linguagens interpretadas a partir da entrada, o servidor deve sanitizar cuidadosamente esta entrada para evitar que comandos maliciosos sejam injetados e executados.
- **Path Traversal:** Se uma ferramenta acessa arquivos com base em parâmetros de entrada, o servidor deve validar e sanitizar esses caminhos para evitar acesso a arquivos ou diretórios não autorizados (por exemplo, bloqueando sequências `../`).
- **Verificações de Tipo e Faixa de Dados:** Servidores devem garantir que os dados de entrada estejam nos tipos esperados (ex: string, número, booleano) e dentro de faixas aceitáveis ou em formatos definidos (ex: regex para URLs).
- **Validação de Schema JSON:** Todos os parâmetros das ferramentas devem ser validados estritamente com seus esquemas JSON definidos. Isso ajuda a capturar requisições mal formatadas precocemente.
- **Atenção do Lado do Cliente**: Embora a validação no servidor seja fundamental, como usuário CrewAI, fique atento aos dados que seus agentes são configurados para enviar a ferramentas MCP, especialmente ao interagir com servidores MCP novos ou menos confiáveis.
### e. Limite de Taxa e Gerenciamento de Recursos
- **Previna Abusos**: Servidores MCP devem implementar limite de taxa para prevenir abusos, seja intencional (ataques de negação de serviço) ou não intencional (ex: um agente mal configurado fazendo muitas requisições).
- **Re-tentativas do Lado do Cliente**: Implemente lógica de repetição sensata em suas tarefas CrewAI se problemas de rede transitórios ou limites de taxa do servidor forem esperados, mas evite re-tentativas agressivas que possam aumentar a carga do servidor.
## 4. Conselhos para Implementação de Servidor MCP Seguro (Para Desenvolvedores)
Se você está desenvolvendo um servidor MCP ao qual agentes CrewAI possam se conectar, considere estas melhores práticas além dos pontos acima:
- **Siga Práticas de Código Seguro**: Adote princípios padrão de programação segura para sua linguagem e framework escolhidos (ex: OWASP Top 10).
- **Princípio do Menor Privilégio**: Certifique-se de que o processo que executa o servidor MCP (especialmente para `Stdio`) tenha apenas as permissões mínimas necessárias. As próprias ferramentas também devem operar com o mínimo de privilégio necessário para executar sua função.
- **Gerenciamento de Dependências**: Mantenha todas as dependências do lado do servidor, incluindo pacotes do sistema operacional, runtimes de linguagem e bibliotecas de terceiros, sempre atualizadas para corrigir vulnerabilidades conhecidas. Use ferramentas para escanear por dependências vulneráveis.
- **Padrões Seguros por Padrão**: Projete seu servidor e suas ferramentas para serem seguros por padrão. Por exemplo, recursos potencialmente arriscados devem ser desabilitados por padrão ou requerer ativação explícita, com avisos claros.
- **Controle de Acesso para Ferramentas**: Implemente mecanismos robustos para controlar quais agentes ou usuários autenticados e autorizados podem acessar ferramentas específicas, especialmente as que são poderosas, sensíveis ou incorram em custos.
- **Tratamento Seguro de Erros**: Servidores não devem expor mensagens detalhadas de erro interno, traces de stack ou informações de debug para o cliente, pois estas podem revelar detalhes internos ou potenciais vulnerabilidades. Logue os erros de forma abrangente no lado do servidor para diagnóstico.
- **Log e Monitoramento Abrangentes**: Implemente um log detalhado de eventos relevantes para segurança (ex: tentativas de autenticação, invocações de ferramenta, erros, mudanças de autorização). Monitore esses logs em busca de atividades suspeitas ou padrões de abuso.
- **Aderência à Especificação de Autorização MCP**: Caso implemente autenticação e autorização, siga estritamente a [especificação de autorização MCP](https://modelcontextprotocol.io/specification/draft/basic/authorization) e as [melhores práticas de segurança OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc9700) relevantes.
- **Auditorias de Segurança Regulares**: Caso seu servidor MCP manipule dados sensíveis, realize operações críticas ou seja exposto publicamente, considere auditorias de segurança periódicas conduzidas por profissionais qualificados.
## 5. Leituras Adicionais
Para informações mais detalhadas sobre segurança MCP, consulte a documentação oficial:
- **[Segurança de Transporte MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations)**
Ao entender essas considerações de segurança e implementar as melhores práticas, você pode aproveitar com segurança o poder dos servidores MCP em seus projetos CrewAI.
Estes pontos não esgotam o assunto, mas cobrem as questões de segurança mais comuns e críticas.
As ameaças continuarão a evoluir, por isso é importante se manter informado e adaptar suas medidas de segurança de acordo.

150
docs/pt-BR/mcp/sse.mdx Normal file
View File

@@ -0,0 +1,150 @@
---
title: Transporte SSE
description: Saiba como conectar o CrewAI a servidores MCP remotos usando Server-Sent Events (SSE) para comunicação em tempo real.
icon: wifi
---
## Visão Geral
Server-Sent Events (SSE) fornecem uma forma padrão para um servidor web enviar atualizações a um cliente através de uma única conexão HTTP de longa duração. No contexto do MCP, SSE é utilizado para que servidores remotos transmitam dados (como respostas de ferramentas) para sua aplicação CrewAI em tempo real.
## Conceitos-Chave
- **Servidores Remotos**: SSE é adequado para servidores MCP hospedados remotamente.
- **Fluxo Unidirecional**: Normalmente, SSE é um canal de comunicação de mão única, do servidor para o cliente.
- **Configuração do `MCPServerAdapter`**: Para SSE, você fornecerá a URL do servidor e especificará o tipo de transporte.
## Conectando via SSE
Você pode se conectar a um servidor MCP baseado em SSE usando duas abordagens principais para gerenciar o ciclo de vida da conexão:
### 1. Conexão Totalmente Gerenciada (Recomendado)
Utilizar um gerenciador de contexto Python (`with` statement) é a abordagem recomendada. Ele lida automaticamente com o estabelecimento e o encerramento da conexão com o servidor MCP SSE.
```python
from crewai import Agent, Task, Crew, Process
from crewai_tools import MCPServerAdapter
server_params = {
"url": "http://localhost:8000/sse", # Replace with your actual SSE server URL
"transport": "sse"
}
# Using MCPServerAdapter with a context manager
try:
with MCPServerAdapter(server_params) as tools:
print(f"Available tools from SSE MCP server: {[tool.name for tool in tools]}")
# Example: Using a tool from the SSE MCP server
sse_agent = Agent(
role="Remote Service User",
goal="Utilize a tool provided by a remote SSE MCP server.",
backstory="An AI agent that connects to external services via SSE.",
tools=tools,
reasoning=True,
verbose=True,
)
sse_task = Task(
description="Fetch real-time stock updates for 'AAPL' using an SSE tool.",
expected_output="The latest stock price for AAPL.",
agent=sse_agent,
markdown=True
)
sse_crew = Crew(
agents=[sse_agent],
tasks=[sse_task],
verbose=True,
process=Process.sequential
)
if tools: # Only kickoff if tools were loaded
result = sse_crew.kickoff() # Add inputs={'stock_symbol': 'AAPL'} if tool requires it
print("\nCrew Task Result (SSE - Managed):\n", result)
else:
print("Skipping crew kickoff as tools were not loaded (check server connection).")
except Exception as e:
print(f"Error connecting to or using SSE MCP server (Managed): {e}")
print("Ensure the SSE MCP server is running and accessible at the specified URL.")
```
<Note>
Substitua `"http://localhost:8000/sse"` pela URL real do seu servidor MCP SSE.
</Note>
### 2. Ciclo de Vida Manual da Conexão
Caso precise de um controle mais detalhado, você pode gerenciar manualmente o ciclo de vida da conexão do `MCPServerAdapter`.
<Info>
Você **DEVE** chamar `mcp_server_adapter.stop()` para garantir que a conexão seja encerrada e os recursos liberados. O uso de um bloco `try...finally` é altamente recomendado.
</Info>
```python
from crewai import Agent, Task, Crew, Process
from crewai_tools import MCPServerAdapter
server_params = {
"url": "http://localhost:8000/sse", # Replace with your actual SSE server URL
"transport": "sse"
}
mcp_server_adapter = None
try:
mcp_server_adapter = MCPServerAdapter(server_params)
mcp_server_adapter.start()
tools = mcp_server_adapter.tools
print(f"Available tools (manual SSE): {[tool.name for tool in tools]}")
manual_sse_agent = Agent(
role="Remote Data Analyst",
goal="Analyze data fetched from a remote SSE MCP server using manual connection management.",
backstory="An AI skilled in handling SSE connections explicitly.",
tools=tools,
verbose=True
)
analysis_task = Task(
description="Fetch and analyze the latest user activity trends from the SSE server.",
expected_output="A summary report of user activity trends.",
agent=manual_sse_agent
)
analysis_crew = Crew(
agents=[manual_sse_agent],
tasks=[analysis_task],
verbose=True,
process=Process.sequential
)
result = analysis_crew.kickoff()
print("\nCrew Task Result (SSE - Manual):\n", result)
except Exception as e:
print(f"An error occurred during manual SSE MCP integration: {e}")
print("Ensure the SSE MCP server is running and accessible.")
finally:
if mcp_server_adapter and mcp_server_adapter.is_connected:
print("Stopping SSE MCP server connection (manual)...")
mcp_server_adapter.stop() # **Crucial: Ensure stop is called**
elif mcp_server_adapter:
print("SSE MCP server adapter was not connected. No stop needed or start failed.")
```
## Considerações de Segurança para SSE
<Warning>
**Ataques de DNS Rebinding**: Transportes SSE podem ser vulneráveis a ataques de DNS rebinding se o servidor MCP não estiver devidamente protegido. Isso pode permitir que sites maliciosos interajam com servidores MCP locais ou da intranet.
</Warning>
Para mitigar esse risco:
- As implementações do servidor MCP devem **validar os cabeçalhos `Origin`** em conexões SSE recebidas.
- Ao rodar servidores MCP SSE locais para desenvolvimento, **faça o bind apenas em `localhost` (`127.0.0.1`)** ao invés de todas as interfaces de rede (`0.0.0.0`).
- Implemente **autenticação adequada** para todas as conexões SSE caso exponham ferramentas ou dados sensíveis.
Para uma visão abrangente das melhores práticas de segurança, consulte nossa página de [Considerações de Segurança](./security.mdx) e a documentação oficial [MCP Transport Security](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations).

133
docs/pt-BR/mcp/stdio.mdx Normal file
View File

@@ -0,0 +1,133 @@
---
title: Transporte Stdio
description: Aprenda como conectar o CrewAI a servidores MCP locais usando o mecanismo de transporte Stdio (Entrada/Saída Padrão).
icon: server
---
## Visão Geral
O transporte Stdio (Entrada/Saída Padrão) é projetado para conectar o `MCPServerAdapter` a servidores MCP locais que se comunicam por meio de seus fluxos de entrada e saída padrão. Isso é normalmente utilizado quando o servidor MCP é um script ou executável rodando na mesma máquina da sua aplicação CrewAI.
## Conceitos-Chave
- **Execução Local**: O transporte Stdio gerencia um processo localmente em execução para o servidor MCP.
- **`StdioServerParameters`**: Esta classe da biblioteca `mcp` é usada para configurar o comando, argumentos e variáveis de ambiente para iniciar o servidor Stdio.
## Conectando via Stdio
Você pode se conectar a um servidor MCP baseado em Stdio usando duas abordagens principais para gerenciar o ciclo de vida da conexão:
### 1. Conexão Totalmente Gerenciada (Recomendado)
Usar um context manager do Python (declaração `with`) é a abordagem recomendada. Ela lida automaticamente com o início do processo do servidor MCP e sua finalização quando o contexto é encerrado.
```python
from crewai import Agent, Task, Crew, Process
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters
import os
# Criar um objeto StdioServerParameters
server_params=StdioServerParameters(
command="python3",
args=["servers/your_stdio_server.py"],
env={"UV_PYTHON": "3.12", **os.environ},
)
with MCPServerAdapter(server_params) as tools:
print(f"Available tools from Stdio MCP server: {[tool.name for tool in tools]}")
# Exemplo: Usando as ferramentas do servidor MCP Stdio em um Agente CrewAI
research_agent = Agent(
role="Local Data Processor",
goal="Process data using a local Stdio-based tool.",
backstory="An AI that leverages local scripts via MCP for specialized tasks.",
tools=tools,
reasoning=True,
verbose=True,
)
processing_task = Task(
description="Process the input data file 'data.txt' and summarize its contents.",
expected_output="A summary of the processed data.",
agent=research_agent,
markdown=True
)
data_crew = Crew(
agents=[research_agent],
tasks=[processing_task],
verbose=True,
process=Process.sequential
)
result = data_crew.kickoff()
print("\nCrew Task Result (Stdio - Managed):\n", result)
```
### 2. Ciclo de Vida Manual da Conexão
Se você precisa de um controle mais refinado sobre quando o processo do servidor MCP Stdio é iniciado e finalizado, pode gerenciar o ciclo de vida do `MCPServerAdapter` manualmente.
<Info>
Você **DEVE** chamar `mcp_server_adapter.stop()` para garantir que o processo do servidor seja finalizado e os recursos, liberados. Recomenda-se fortemente o uso de um bloco `try...finally`.
</Info>
```python
from crewai import Agent, Task, Crew, Process
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters
import os
# Criar um objeto StdioServerParameters
stdio_params=StdioServerParameters(
command="python3",
args=["servers/your_stdio_server.py"],
env={"UV_PYTHON": "3.12", **os.environ},
)
mcp_server_adapter = MCPServerAdapter(server_params=stdio_params)
try:
mcp_server_adapter.start() # Inicia manualmente a conexão e o processo do servidor
tools = mcp_server_adapter.tools
print(f"Available tools (manual Stdio): {[tool.name for tool in tools]}")
# Exemplo: Usando as ferramentas com sua configuração de Agent, Task, Crew
manual_agent = Agent(
role="Local Task Executor",
goal="Execute a specific local task using a manually managed Stdio tool.",
backstory="An AI proficient in controlling local processes via MCP.",
tools=tools,
verbose=True
)
manual_task = Task(
description="Execute the 'perform_analysis' command via the Stdio tool.",
expected_output="Results of the analysis.",
agent=manual_agent
)
manual_crew = Crew(
agents=[manual_agent],
tasks=[manual_task],
verbose=True,
process=Process.sequential
)
result = manual_crew.kickoff() # As entradas reais dependem da sua ferramenta
print("\nCrew Task Result (Stdio - Manual):\n", result)
except Exception as e:
print(f"An error occurred during manual Stdio MCP integration: {e}")
finally:
if mcp_server_adapter and mcp_server_adapter.is_connected: # Verifica se está conectado antes de parar
print("Stopping Stdio MCP server connection (manual)...")
mcp_server_adapter.stop() # **Crucial: Assegure que stop seja chamado**
elif mcp_server_adapter: # Se o adaptador existe mas não está conectado (ex.: start falhou)
print("Stdio MCP server adapter was not connected. No stop needed or start failed.")
```
Lembre-se de substituir caminhos e comandos de exemplo pelos detalhes reais do seu servidor Stdio. O parâmetro `env` em `StdioServerParameters` pode ser usado para definir variáveis de ambiente para o processo do servidor, o que pode ser útil para configurar seu comportamento ou fornecer caminhos necessários (como `PYTHONPATH`).

135
docs/pt-BR/mcp/streamable-http.mdx Normal file
View File

@@ -0,0 +1,135 @@
---
title: Transporte HTTP Streamable
description: Saiba como conectar o CrewAI a servidores MCP remotos usando o transporte HTTP Streamable flexível.
icon: globe
---
## Visão Geral
O transporte HTTP Streamable oferece uma maneira flexível de se conectar a servidores MCP remotos. Ele é frequentemente baseado em HTTP e pode suportar vários padrões de comunicação, incluindo requisição-resposta e streaming, às vezes utilizando Server-Sent Events (SSE) para fluxos do servidor para o cliente dentro de uma interação HTTP mais ampla.
## Conceitos-Chave
- **Servidores Remotos**: Projetado para servidores MCP hospedados remotamente.
- **Flexibilidade**: Pode suportar padrões de interação mais complexos do que SSE puro, potencialmente incluindo comunicação bidirecional se o servidor implementá-la.
- **Configuração do `MCPServerAdapter`**: Você precisará fornecer a URL base do servidor para comunicação MCP e especificar `"streamable-http"` como o tipo de transporte.
## Conectando via HTTP Streamable
Você tem dois métodos principais para gerenciar o ciclo de vida da conexão com um servidor MCP HTTP Streamable:
### 1. Conexão Totalmente Gerenciada (Recomendado)
A abordagem recomendada é usar um gerenciador de contexto Python (`with` statement), que lida automaticamente com a configuração e encerramento da conexão.
```python
from crewai import Agent, Task, Crew, Process
from crewai_tools import MCPServerAdapter
server_params = {
"url": "http://localhost:8001/mcp", # Replace with your actual Streamable HTTP server URL
"transport": "streamable-http"
}
try:
with MCPServerAdapter(server_params) as tools:
print(f"Available tools from Streamable HTTP MCP server: {[tool.name for tool in tools]}")
http_agent = Agent(
role="HTTP Service Integrator",
goal="Utilize tools from a remote MCP server via Streamable HTTP.",
backstory="An AI agent adept at interacting with complex web services.",
tools=tools,
verbose=True,
)
http_task = Task(
description="Perform a complex data query using a tool from the Streamable HTTP server.",
expected_output="The result of the complex data query.",
agent=http_agent,
)
http_crew = Crew(
agents=[http_agent],
tasks=[http_task],
verbose=True,
process=Process.sequential
)
result = http_crew.kickoff()
print("\nCrew Task Result (Streamable HTTP - Managed):\n", result)
except Exception as e:
print(f"Error connecting to or using Streamable HTTP MCP server (Managed): {e}")
print("Ensure the Streamable HTTP MCP server is running and accessible at the specified URL.")
```
**Nota:** Substitua `"http://localhost:8001/mcp"` pela URL real do seu servidor MCP HTTP Streamable.
### 2. Ciclo de Vida da Conexão Manual
Para cenários que exigem controle mais explícito, você pode gerenciar a conexão do `MCPServerAdapter` manualmente.
<Info>
É **crítico** chamar `mcp_server_adapter.stop()` quando terminar para fechar a conexão e liberar recursos. Usar um bloco `try...finally` é a forma mais segura de garantir isso.
</Info>
```python
from crewai import Agent, Task, Crew, Process
from crewai_tools import MCPServerAdapter
server_params = {
"url": "http://localhost:8001/mcp", # Replace with your actual Streamable HTTP server URL
"transport": "streamable-http"
}
mcp_server_adapter = None
try:
mcp_server_adapter = MCPServerAdapter(server_params)
mcp_server_adapter.start()
tools = mcp_server_adapter.tools
print(f"Available tools (manual Streamable HTTP): {[tool.name for tool in tools]}")
manual_http_agent = Agent(
role="Advanced Web Service User",
goal="Interact with an MCP server using manually managed Streamable HTTP connections.",
backstory="An AI specialist in fine-tuning HTTP-based service integrations.",
tools=tools,
verbose=True
)
data_processing_task = Task(
description="Submit data for processing and retrieve results via Streamable HTTP.",
expected_output="Processed data or confirmation.",
agent=manual_http_agent
)
data_crew = Crew(
agents=[manual_http_agent],
tasks=[data_processing_task],
verbose=True,
process=Process.sequential
)
result = data_crew.kickoff()
print("\nCrew Task Result (Streamable HTTP - Manual):\n", result)
except Exception as e:
print(f"An error occurred during manual Streamable HTTP MCP integration: {e}")
print("Ensure the Streamable HTTP MCP server is running and accessible.")
finally:
if mcp_server_adapter and mcp_server_adapter.is_connected:
print("Stopping Streamable HTTP MCP server connection (manual)...")
mcp_server_adapter.stop() # **Crucial: Ensure stop is called**
elif mcp_server_adapter:
print("Streamable HTTP MCP server adapter was not connected. No stop needed or start failed.")
```
## Considerações de Segurança
Ao utilizar o transporte HTTP Streamable, as melhores práticas gerais de segurança web são fundamentais:
- **Use HTTPS**: Sempre prefira HTTPS (HTTP Seguro) para as URLs do seu servidor MCP para criptografar os dados em trânsito.
- **Autenticação**: Implemente mecanismos robustos de autenticação se seu servidor MCP expuser ferramentas ou dados sensíveis.
- **Validação de Entrada**: Garanta que seu servidor MCP valide todas as requisições e parâmetros recebidos.
Para um guia abrangente sobre como proteger suas integrações MCP, consulte nossa página de [Considerações de Segurança](./security.mdx) e a documentação oficial de [Segurança em Transportes MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations).

126
docs/pt-BR/observability/agentops.mdx Normal file
View File

@@ -0,0 +1,126 @@
---
title: Integração com AgentOps
description: Entendendo e registrando a performance do seu agente com AgentOps.
icon: paperclip
---
# Introdução
Observabilidade é um aspecto fundamental no desenvolvimento e implantação de agentes de IA conversacional. Ela permite que desenvolvedores compreendam como seus agentes estão performando,
como eles estão interagindo com os usuários e como utilizam ferramentas externas e APIs.
AgentOps é um produto independente do CrewAI que fornece uma solução completa de observabilidade para agentes.
## AgentOps
[AgentOps](https://agentops.ai/?=crew) oferece replay de sessões, métricas e monitoramento para agentes.
Em um alto nível, o AgentOps oferece a capacidade de monitorar custos, uso de tokens, latência, falhas do agente, estatísticas de sessão e muito mais.
Para mais informações, confira o [Repositório do AgentOps](https://github.com/AgentOps-AI/agentops).
### Visão Geral
AgentOps fornece monitoramento para agentes em desenvolvimento e produção.
Disponibiliza um dashboard para acompanhamento de performance dos agentes, replay de sessões e relatórios personalizados.
Além disso, o AgentOps traz análises detalhadas das sessões para visualizar interações do agente Crew, chamadas LLM e uso de ferramentas em tempo real.
Esse recurso é útil para depuração e entendimento de como os agentes interagem com usuários e entre si.
![Visão geral de uma série selecionada de execuções de sessões do agente](/images/agentops-overview.png)
![Visão geral das análises detalhadas de sessões para examinar execuções de agentes](/images/agentops-session.png)
![Visualizando um gráfico de execução passo a passo do replay do agente](/images/agentops-replay.png)
### Funcionalidades
- **Gerenciamento e Rastreamento de Custos de LLM**: Acompanhe gastos com provedores de modelos fundamentais.
- **Análises de Replay**: Assista gráficos de execução do agente, passo a passo.
- **Detecção de Pensamento Recursivo**: Identifique quando agentes entram em loops infinitos.
- **Relatórios Personalizados**: Crie análises customizadas sobre a performance dos agentes.
- **Dashboard Analítico**: Monitore estatísticas gerais de agentes em desenvolvimento e produção.
- **Teste de Modelos Públicos**: Teste seus agentes em benchmarks e rankings.
- **Testes Personalizados**: Execute seus agentes em testes específicos de domínio.
- **Depuração com Viagem no Tempo**: Reinicie suas sessões a partir de checkpoints.
- **Conformidade e Segurança**: Crie registros de auditoria e detecte possíveis ameaças como uso de palavrões e vazamento de dados pessoais.
- **Detecção de Prompt Injection**: Identifique possíveis injeções de código e vazamentos de segredos.
### Utilizando o AgentOps
<Steps>
<Step title="Crie uma Chave de API">
Crie uma chave de API de usuário aqui: [Create API Key](https://app.agentops.ai/account)
</Step>
<Step title="Configure seu Ambiente">
Adicione sua chave API nas variáveis de ambiente:
```bash
AGENTOPS_API_KEY=<YOUR_AGENTOPS_API_KEY>
```
</Step>
<Step title="Instale o AgentOps">
Instale o AgentOps com:
```bash
pip install 'crewai[agentops]'
```
ou
```bash
pip install agentops
```
</Step>
<Step title="Inicialize o AgentOps">
Antes de utilizar o `Crew` no seu script, inclua estas linhas:
```python
import agentops
agentops.init()
```
Isso irá iniciar uma sessão do AgentOps e também rastrear automaticamente os agentes Crew. Para mais detalhes sobre como adaptar sistemas de agentes mais complexos,
confira a [documentação do AgentOps](https://docs.agentops.ai) ou participe do [Discord](https://discord.gg/j4f3KbeH).
</Step>
</Steps>
### Exemplos de Crew + AgentOps
<CardGroup cols={3}>
<Card
title="Vaga de Emprego"
color="#F3A78B"
href="https://github.com/joaomdmoura/crewAI-examples/tree/main/job-posting"
icon="briefcase"
iconType="solid"
>
Exemplo de um agente Crew que gera vagas de emprego.
</Card>
<Card
title="Validador de Markdown"
color="#F3A78B"
href="https://github.com/joaomdmoura/crewAI-examples/tree/main/markdown_validator"
icon="markdown"
iconType="solid"
>
Exemplo de um agente Crew que valida arquivos Markdown.
</Card>
<Card
title="Post no Instagram"
color="#F3A78B"
href="https://github.com/joaomdmoura/crewAI-examples/tree/main/instagram_post"
icon="square-instagram"
iconType="brands"
>
Exemplo de um agente Crew que gera posts para Instagram.
</Card>
</CardGroup>
### Mais Informações
Para começar, crie uma [conta AgentOps](https://agentops.ai/?=crew).
Para sugestões de funcionalidades ou relatos de bugs, entre em contato com o time do AgentOps pelo [Repositório do AgentOps](https://github.com/AgentOps-AI/agentops).
#### Links Extras
<a href="https://twitter.com/agentopsai/">🐦 Twitter</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="https://discord.gg/JHPt4C7r">📢 Discord</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="https://app.agentops.ai/?=crew">🖇️ Dashboard AgentOps</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="https://docs.agentops.ai/introduction">📙 Documentação</a>

151
docs/pt-BR/observability/arize-phoenix.mdx Normal file
View File

@@ -0,0 +1,151 @@
---
title: Arize Phoenix
description: Integração do Arize Phoenix para CrewAI com OpenTelemetry e OpenInference
icon: magnifying-glass-chart
---
# Integração com Arize Phoenix
Este guia demonstra como integrar o **Arize Phoenix** ao **CrewAI** usando o OpenTelemetry através do [OpenInference](https://github.com/openinference/openinference) SDK. Ao final deste guia, você será capaz de rastrear seus agentes CrewAI e depurá-los com facilidade.
> **O que é o Arize Phoenix?** O [Arize Phoenix](https://phoenix.arize.com) é uma plataforma de observabilidade de LLM que oferece rastreamento e avaliação para aplicações de IA.
[![Assista a um vídeo demonstrando a nossa integração com o Phoenix](https://storage.googleapis.com/arize-assets/fixtures/setup_crewai.png)](https://www.youtube.com/watch?v=Yc5q3l6F7Ww)
## Primeiros Passos
Vamos percorrer um exemplo simples de uso do CrewAI e integração com o Arize Phoenix via OpenTelemetry utilizando o OpenInference.
Você também pode acessar este guia no [Google Colab](https://colab.research.google.com/github/Arize-ai/phoenix/blob/main/tutorials/tracing/crewai_tracing_tutorial.ipynb).
### Passo 1: Instale as Dependências
```bash
pip install openinference-instrumentation-crewai crewai crewai-tools arize-phoenix-otel
```
### Passo 2: Configure as Variáveis de Ambiente
Configure as chaves de API do Phoenix Cloud e ajuste o OpenTelemetry para enviar rastros ao Phoenix. O Phoenix Cloud é uma versão hospedada do Arize Phoenix, mas não é obrigatório para utilizar esta integração.
Você pode obter uma chave de API gratuita do Serper [aqui](https://serper.dev/).
```python
import os
from getpass import getpass
# Obtenha suas credenciais do Phoenix Cloud
PHOENIX_API_KEY = getpass("🔑 Digite sua Phoenix Cloud API Key: ")
# Obtenha as chaves de API para os serviços
OPENAI_API_KEY = getpass("🔑 Digite sua OpenAI API key: ")
SERPER_API_KEY = getpass("🔑 Digite sua Serper API key: ")
# Defina as variáveis de ambiente
os.environ["PHOENIX_CLIENT_HEADERS"] = f"api_key={PHOENIX_API_KEY}"
os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "https://app.phoenix.arize.com" # Phoenix Cloud, altere para seu endpoint se estiver utilizando uma instância self-hosted
os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY
os.environ["SERPER_API_KEY"] = SERPER_API_KEY
```
### Passo 3: Inicialize o OpenTelemetry com o Phoenix
Inicialize o SDK de instrumentação OpenTelemetry do OpenInference para começar a capturar rastros e enviá-los ao Phoenix.
```python
from phoenix.otel import register
tracer_provider = register(
project_name="crewai-tracing-demo",
auto_instrument=True,
)
```
### Passo 4: Crie uma Aplicação CrewAI
Vamos criar uma aplicação CrewAI em que dois agentes colaboram para pesquisar e escrever um post de blog sobre avanços em IA.
```python
from crewai import Agent, Crew, Process, Task
from crewai_tools import SerperDevTool
from openinference.instrumentation.crewai import CrewAIInstrumentor
from phoenix.otel import register
# configure o monitoramento para seu crew
tracer_provider = register(
endpoint="http://localhost:6006/v1/traces")
CrewAIInstrumentor().instrument(skip_dep_check=True, tracer_provider=tracer_provider)
search_tool = SerperDevTool()
# Defina seus agentes com papéis e objetivos
researcher = Agent(
role="Senior Research Analyst",
goal="Uncover cutting-edge developments in AI and data science",
backstory="""You work at a leading tech think tank.
Your expertise lies in identifying emerging trends.
You have a knack for dissecting complex data and presenting actionable insights.""",
verbose=True,
allow_delegation=False,
# You can pass an optional llm attribute specifying what model you wanna use.
# llm=ChatOpenAI(model_name="gpt-3.5", temperature=0.7),
tools=[search_tool],
)
writer = Agent(
role="Tech Content Strategist",
goal="Craft compelling content on tech advancements",
backstory="""You are a renowned Content Strategist, known for your insightful and engaging articles.
You transform complex concepts into compelling narratives.""",
verbose=True,
allow_delegation=True,
)
# Crie tarefas para seus agentes
task1 = Task(
description="""Conduct a comprehensive analysis of the latest advancements in AI in 2024.
Identify key trends, breakthrough technologies, and potential industry impacts.""",
expected_output="Full analysis report in bullet points",
agent=researcher,
)
task2 = Task(
description="""Using the insights provided, develop an engaging blog
post that highlights the most significant AI advancements.
Your post should be informative yet accessible, catering to a tech-savvy audience.
Make it sound cool, avoid complex words so it doesn't sound like AI.""",
expected_output="Full blog post of at least 4 paragraphs",
agent=writer,
)
# Instancie seu crew com um processo sequencial
crew = Crew(
agents=[researcher, writer], tasks=[task1, task2], verbose=1, process=Process.sequential
)
# Coloque seu crew para trabalhar!
result = crew.kickoff()
print("######################")
print(result)
```
### Passo 5: Visualize os Rastros no Phoenix
Após executar o agente, você poderá visualizar os rastros gerados pela sua aplicação CrewAI no Phoenix. Você verá etapas detalhadas das interações dos agentes e chamadas de LLM, o que pode ajudar na depuração e otimização dos seus agentes de IA.
Acesse sua conta Phoenix Cloud e navegue até o projeto que você especificou no parâmetro `project_name`. Você verá uma visualização de linha do tempo do seu rastro, incluindo todas as interações dos agentes, uso de ferramentas e chamadas LLM.
![Exemplo de rastro no Phoenix mostrando interações de agentes](https://storage.googleapis.com/arize-assets/fixtures/crewai_traces.png)
### Informações de Compatibilidade de Versão
- Python 3.8+
- CrewAI >= 0.86.0
- Arize Phoenix >= 7.0.1
- OpenTelemetry SDK >= 1.31.0
### Referências
- [Documentação do Phoenix](https://docs.arize.com/phoenix/) - Visão geral da plataforma Phoenix.
- [Documentação do CrewAI](https://docs.crewai.com/) - Visão geral do framework CrewAI.
- [Documentação do OpenTelemetry](https://opentelemetry.io/docs/) - Guia do OpenTelemetry
- [OpenInference GitHub](https://github.com/openinference/openinference) - Código-fonte do SDK OpenInference.

107
docs/pt-BR/observability/langfuse.mdx Normal file
View File

@@ -0,0 +1,107 @@
---
title: Integração Langfuse
description: Saiba como integrar o Langfuse ao CrewAI via OpenTelemetry usando OpenLit
icon: vials
---
# Integre o Langfuse ao CrewAI
Este notebook demonstra como integrar o **Langfuse** ao **CrewAI** usando OpenTelemetry via o SDK **OpenLit**. Ao final deste notebook, você será capaz de rastrear suas aplicações CrewAI com o Langfuse para melhorar a observabilidade e a depuração.
> **O que é Langfuse?** [Langfuse](https://langfuse.com) é uma plataforma open-source de engenharia LLM. Ela fornece recursos de rastreamento e monitoramento para aplicações LLM, ajudando desenvolvedores a depurar, analisar e otimizar seus sistemas de IA. O Langfuse se integra com várias ferramentas e frameworks através de integrações nativas, OpenTelemetry e APIs/SDKs.
[![Vídeo de Visão Geral do Langfuse](https://github.com/user-attachments/assets/3926b288-ff61-4b95-8aa1-45d041c70866)](https://langfuse.com/watch-demo)
## Primeiros Passos
Vamos passar por um exemplo simples usando CrewAI e integrando ao Langfuse via OpenTelemetry utilizando o OpenLit.
### Passo 1: Instale as Dependências
```python
%pip install langfuse openlit crewai crewai_tools
```
### Passo 2: Configure as Variáveis de Ambiente
Defina suas chaves de API do Langfuse e configure as opções de exportação do OpenTelemetry para enviar os traces ao Langfuse. Consulte a [Documentação Langfuse OpenTelemetry](https://langfuse.com/docs/opentelemetry/get-started) para mais informações sobre o endpoint Langfuse OpenTelemetry `/api/public/otel` e autenticação.
```python
import os
# Obtenha as chaves do seu projeto na página de configurações do projeto: https://cloud.langfuse.com
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" # 🇪🇺 Região UE
# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 Região EUA
# Sua chave OpenAI
os.environ["OPENAI_API_KEY"] = "sk-proj-..."
```
Com as variáveis de ambiente configuradas, agora podemos inicializar o cliente Langfuse. A função get_client() inicializa o cliente Langfuse usando as credenciais fornecidas nas variáveis de ambiente.
```python
from langfuse import get_client
langfuse = get_client()
# Verificar conexão
if langfuse.auth_check():
print("Cliente Langfuse autenticado e pronto!")
else:
print("Falha na autenticação. Verifique suas credenciais e host.")
```
### Passo 3: Inicialize o OpenLit
Inicialize o SDK de instrumentação OpenTelemetry do OpenLit para começar a capturar traces do OpenTelemetry.
```python
import openlit
openlit.init()
```
### Passo 4: Crie uma Aplicação Simples CrewAI
Vamos criar uma aplicação simples CrewAI onde múltiplos agentes colaboram para responder à pergunta de um usuário.
```python
from crewai import Agent, Task, Crew
from crewai_tools import (
WebsiteSearchTool
)
web_rag_tool = WebsiteSearchTool()
writer = Agent(
role="Writer",
goal="Você torna a matemática envolvente e compreensível para crianças pequenas através de poesias",
backstory="Você é especialista em escrever haicais mas não sabe nada de matemática.",
tools=[web_rag_tool],
)
task = Task(description=("O que é {multiplicação}?"),
expected_output=("Componha um haicai que inclua a resposta."),
agent=writer)
crew = Crew(
agents=[writer],
tasks=[task],
share_crew=False
)
```
### Passo 5: Veja os Traces no Langfuse
Após rodar o agente, você pode visualizar os traces gerados pela sua aplicação CrewAI no [Langfuse](https://cloud.langfuse.com). Você verá etapas detalhadas das interações do LLM, o que pode ajudar na depuração e otimização do seu agente de IA.
![Exemplo de trace CrewAI no Langfuse](https://langfuse.com/images/cookbook/integration_crewai/crewai-example-trace.png)
_[Exemplo público de trace no Langfuse](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/e2cf380ffc8d47d28da98f136140642b?timestamp=2025-02-05T15%3A12%3A02.717Z&observation=3b32338ee6a5d9af)_
## Referências
- [Documentação Langfuse OpenTelemetry](https://langfuse.com/docs/opentelemetry/get-started)

72
docs/pt-BR/observability/langtrace.mdx Normal file
View File

@@ -0,0 +1,72 @@
---
title: Integração com Langtrace
description: Como monitorar custo, latência e desempenho dos Agentes CrewAI usando o Langtrace, uma ferramenta externa de observabilidade.
icon: chart-line
---
# Visão Geral do Langtrace
O Langtrace é uma ferramenta externa e open-source que auxilia na configuração de observabilidade e avaliações para Modelos de Linguagem de Grande Porte (LLMs), frameworks de LLM e Bancos de Dados Vetoriais.
Apesar de não ser integrado diretamente ao CrewAI, o Langtrace pode ser utilizado em conjunto com o CrewAI para fornecer uma visibilidade aprofundada sobre o custo, latência e desempenho dos seus Agentes CrewAI.
Essa integração permite o registro de hiperparâmetros, o monitoramento de regressões de desempenho e o estabelecimento de um processo de melhoria contínua dos seus Agentes.
![Visão geral de uma seleção de execuções de sessões de agentes](/images/langtrace1.png)
![Visão geral dos traces de agentes](/images/langtrace2.png)
![Visão detalhada dos traces de LLM](/images/langtrace3.png)
## Instruções de Configuração
<Steps>
<Step title="Crie uma conta no Langtrace">
Cadastre-se acessando [https://langtrace.ai/signup](https://langtrace.ai/signup).
</Step>
<Step title="Crie um projeto">
Defina o tipo do projeto como `CrewAI` e gere uma chave de API.
</Step>
<Step title="Instale o Langtrace no seu projeto CrewAI">
Use o seguinte comando:
```bash
pip install langtrace-python-sdk
```
</Step>
<Step title="Importe o Langtrace">
Importe e inicialize o Langtrace no início do seu script, antes de quaisquer imports do CrewAI:
```python
from langtrace_python_sdk import langtrace
langtrace.init(api_key='<LANGTRACE_API_KEY>')
# Agora importe os módulos do CrewAI
from crewai import Agent, Task, Crew
```
</Step>
</Steps>
### Funcionalidades e Sua Aplicação no CrewAI
1. **Rastreamento de Token e Custo do LLM**
- Monitore o uso de tokens e os custos associados para cada interação dos agentes CrewAI.
2. **Gráfico de Trace para Etapas de Execução**
- Visualize o fluxo de execução das suas tarefas CrewAI, incluindo latência e logs.
- Útil para identificar gargalos nos fluxos de trabalho dos seus agentes.
3. **Curadoria de Dataset com Anotação Manual**
- Crie conjuntos de dados a partir das saídas das suas tarefas CrewAI para futuros treinamentos ou avaliações.
4. **Versionamento e Gerenciamento de Prompt**
- Acompanhe as diferentes versões de prompts utilizados em seus agentes CrewAI.
- Útil para testes A/B e otimização de desempenho dos agentes.
5. **Playground de Prompt com Comparações de Modelos**
- Teste e compare diferentes prompts e modelos para seus agentes CrewAI antes da implantação.
6. **Testes e Avaliações**
- Configure testes automatizados para seus agentes e tarefas CrewAI.

150
docs/pt-BR/observability/maxim.mdx Normal file
View File

@@ -0,0 +1,150 @@
---
title: Integração Maxim
description: Inicie o monitoramento, avaliação e observabilidade de agentes
icon: bars-staggered
---
# Integração Maxim
Maxim AI oferece monitoramento completo de agentes, avaliação e observabilidade para suas aplicações CrewAI. Com a integração de uma linha do Maxim, você pode facilmente rastrear e analisar interações dos agentes, métricas de desempenho e muito mais.
## Funcionalidades: Integração com Uma Linha
- **Rastreamento de Agentes de Ponta a Ponta**: Monitore todo o ciclo de vida dos seus agentes
- **Análise de Desempenho**: Acompanhe latência, tokens consumidos e custos
- **Monitoramento de Hiperparâmetros**: Visualize detalhes de configuração das execuções dos agentes
- **Rastreamento de Chamadas de Ferramentas**: Observe quando e como os agentes usam suas ferramentas
- **Visualização Avançada**: Entenda as trajetórias dos agentes através de dashboards intuitivos
## Começando
### Pré-requisitos
- Python versão >=3.10
- Uma conta Maxim ([cadastre-se aqui](https://getmaxim.ai/))
- Um projeto CrewAI
### Instalação
Instale o SDK do Maxim via pip:
```python
pip install maxim-py>=3.6.2
```
Ou adicione ao seu `requirements.txt`:
```
maxim-py>=3.6.2
```
### Configuração Básica
### 1. Configure as variáveis de ambiente
```python
### Configuração de Variáveis de Ambiente
# Crie um arquivo `.env` na raiz do seu projeto:
# Configuração da API Maxim
MAXIM_API_KEY=your_api_key_here
MAXIM_LOG_REPO_ID=your_repo_id_here
```
### 2. Importe os pacotes necessários
```python
from crewai import Agent, Task, Crew, Process
from maxim import Maxim
from maxim.logger.crewai import instrument_crewai
```
### 3. Inicialize o Maxim com sua chave de API
```python
# Inicialize o logger do Maxim
logger = Maxim().logger()
# Instrumente o CrewAI com apenas uma linha
instrument_crewai(logger)
```
### 4. Crie e execute sua aplicação CrewAI normalmente
```python
# Crie seu agente
researcher = Agent(
role='Senior Research Analyst',
goal='Uncover cutting-edge developments in AI',
backstory="You are an expert researcher at a tech think tank...",
verbose=True,
llm=llm
)
# Defina a tarefa
research_task = Task(
description="Research the latest AI advancements...",
expected_output="",
agent=researcher
)
# Configure e execute a crew
crew = Crew(
agents=[researcher],
tasks=[research_task],
verbose=True
)
try:
result = crew.kickoff()
finally:
maxim.cleanup() # Garanta o cleanup mesmo em caso de erros
```
É isso! Todas as interações dos seus agentes CrewAI agora serão registradas e estarão disponíveis em seu painel Maxim.
Confira este Google Colab Notebook para referência rápida – [Notebook](https://colab.research.google.com/drive/1ZKIZWsmgQQ46n8TH9zLsT1negKkJA6K8?usp=sharing)
## Visualizando Seus Rastreamentos
Após executar sua aplicação CrewAI:
![Exemplo de rastreamento no Maxim mostrando interações de agentes](https://raw.githubusercontent.com/maximhq/maxim-docs/master/images/Screenshot2025-05-14at12.10.58PM.png)
1. Faça login no seu [Painel Maxim](https://getmaxim.ai/dashboard)
2. Navegue até seu repositório
3. Visualize rastreamentos detalhados de agentes, incluindo:
- Conversas dos agentes
- Padrões de uso de ferramentas
- Métricas de desempenho
- Análises de custos
## Solução de Problemas
### Problemas Comuns
- **Nenhum rastreamento aparecendo**: Certifique-se de que sua chave de API e o ID do repositório estão corretos
- Certifique-se de que você **chamou `instrument_crewai()`** ***antes*** de executar sua crew. Isso inicializa corretamente os hooks de logging.
- Defina `debug=True` na chamada do `instrument_crewai()` para expor erros internos:
```python
instrument_crewai(logger, debug=True)
```
- Configure seus agentes com `verbose=True` para capturar logs detalhados:
```python
agent = CrewAgent(..., verbose=True)
```
- Verifique cuidadosamente se `instrument_crewai()` foi chamado **antes** de criar ou executar agentes. Isso pode parecer óbvio, mas é um erro comum.
### Suporte
Se você encontrar algum problema:
- Consulte a [Documentação do Maxim](https://getmaxim.ai/docs)
- Maxim Github [Link](https://github.com/maximhq)

205
docs/pt-BR/observability/mlflow.mdx Normal file
View File

@@ -0,0 +1,205 @@
---
title: Integração com MLflow
description: Comece rapidamente a monitorar seus Agents com MLflow.
icon: bars-staggered
---
# Visão Geral do MLflow
[MLflow](https://mlflow.org/) é uma plataforma open-source que auxilia profissionais e equipes de machine learning a lidar com as complexidades do processo de aprendizagem de máquina.
Ela oferece um recurso de tracing que aprimora a observabilidade de LLMs em suas aplicações de IA Generativa, capturando informações detalhadas sobre a execução dos serviços de sua aplicação.
O tracing fornece uma forma de registrar os inputs, outputs e metadados associados a cada etapa intermediária de uma requisição, permitindo que você identifique facilmente a origem de bugs e comportamentos inesperados.
![Visão geral do uso de tracing MLflow com crewAI](/images/mlflow-tracing.gif)
### Funcionalidades
- **Painel de Tracing**: Monitore as atividades dos seus agentes crewAI com painéis detalhados que incluem entradas, saídas e metadados dos spans.
- **Tracing Automatizado**: Uma integração totalmente automatizada com crewAI, que pode ser habilitada executando `mlflow.crewai.autolog()`.
- **Instrumentação Manual de Tracing com pouco esforço**: Personalize a instrumentação dos traces usando as APIs de alto nível do MLflow, como decorators, wrappers de funções e context managers.
- **Compatibilidade com OpenTelemetry**: O MLflow Tracing suporta a exportação de traces para um OpenTelemetry Collector, que pode então ser usado para exportar traces para diversos backends como Jaeger, Zipkin e AWS X-Ray.
- **Empacote e Faça Deploy dos Agents**: Empacote e faça deploy de seus agents crewAI em um servidor de inferência com diversas opções de destino.
- **Hospede LLMs com Segurança**: Hospede múltiplos LLMs de vários provedores em um endpoint unificado através do gateway do MFflow.
- **Avaliação**: Avalie seus agents crewAI com uma ampla variedade de métricas utilizando a API conveniente `mlflow.evaluate()`.
## Instruções de Configuração
<Steps>
<Step title="Instale o pacote MLflow">
```shell
# A integração crewAI está disponível no mlflow>=2.19.0
pip install mlflow
```
</Step>
<Step title="Inicie o servidor de tracking do MFflow">
```shell
# Este processo é opcional, mas é recomendado utilizar o servidor de tracking do MLflow para melhor visualização e mais funcionalidades.
mlflow server
```
</Step>
<Step title="Inicialize o MLflow em sua aplicação">
Adicione as duas linhas a seguir ao código da sua aplicação:
```python
import mlflow
mlflow.crewai.autolog()
# Opcional: Defina uma tracking URI e um nome de experimento caso utilize um servidor de tracking
mlflow.set_tracking_uri("http://localhost:5000")
mlflow.set_experiment("CrewAI")
```
Exemplo de uso para tracing de Agents do CrewAI:
```python
from crewai import Agent, Crew, Task
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource
from crewai_tools import SerperDevTool, WebsiteSearchTool
from textwrap import dedent
content = "Users name is John. He is 30 years old and lives in San Francisco."
string_source = StringKnowledgeSource(
content=content, metadata={"preference": "personal"}
)
search_tool = WebsiteSearchTool()
class TripAgents:
def city_selection_agent(self):
return Agent(
role="City Selection Expert",
goal="Select the best city based on weather, season, and prices",
backstory="An expert in analyzing travel data to pick ideal destinations",
tools=[
search_tool,
],
verbose=True,
)
def local_expert(self):
return Agent(
role="Local Expert at this city",
goal="Provide the BEST insights about the selected city",
backstory="""A knowledgeable local guide with extensive information
about the city, it's attractions and customs""",
tools=[search_tool],
verbose=True,
)
class TripTasks:
def identify_task(self, agent, origin, cities, interests, range):
return Task(
description=dedent(
f"""
Analyze and select the best city for the trip based
on specific criteria such as weather patterns, seasonal
events, and travel costs. This task involves comparing
multiple cities, considering factors like current weather
conditions, upcoming cultural or seasonal events, and
overall travel expenses.
Your final answer must be a detailed
report on the chosen city, and everything you found out
about it, including the actual flight costs, weather
forecast and attractions.
Traveling from: {origin}
City Options: {cities}
Trip Date: {range}
Traveler Interests: {interests}
"""
),
agent=agent,
expected_output="Detailed report on the chosen city including flight costs, weather forecast, and attractions",
)
def gather_task(self, agent, origin, interests, range):
return Task(
description=dedent(
f"""
As a local expert on this city you must compile an
in-depth guide for someone traveling there and wanting
to have THE BEST trip ever!
Gather information about key attractions, local customs,
special events, and daily activity recommendations.
Find the best spots to go to, the kind of place only a
local would know.
This guide should provide a thorough overview of what
the city has to offer, including hidden gems, cultural
hotspots, must-visit landmarks, weather forecasts, and
high level costs.
The final answer must be a comprehensive city guide,
rich in cultural insights and practical tips,
tailored to enhance the travel experience.
Trip Date: {range}
Traveling from: {origin}
Traveler Interests: {interests}
"""
),
agent=agent,
expected_output="Comprehensive city guide including hidden gems, cultural hotspots, and practical travel tips",
)
class TripCrew:
def __init__(self, origin, cities, date_range, interests):
self.cities = cities
self.origin = origin
self.interests = interests
self.date_range = date_range
def run(self):
agents = TripAgents()
tasks = TripTasks()
city_selector_agent = agents.city_selection_agent()
local_expert_agent = agents.local_expert()
identify_task = tasks.identify_task(
city_selector_agent,
self.origin,
self.cities,
self.interests,
self.date_range,
)
gather_task = tasks.gather_task(
local_expert_agent, self.origin, self.interests, self.date_range
)
crew = Crew(
agents=[city_selector_agent, local_expert_agent],
tasks=[identify_task, gather_task],
verbose=True,
memory=True,
knowledge={
"sources": [string_source],
"metadata": {"preference": "personal"},
},
)
result = crew.kickoff()
return result
trip_crew = TripCrew("California", "Tokyo", "Dec 12 - Dec 20", "sports")
result = trip_crew.run()
print(result)
```
Consulte a [Documentação de Tracing do MLflow](https://mlflow.org/docs/latest/llms/tracing/index.html) para mais configurações e casos de uso.
</Step>
<Step title="Visualize as atividades dos Agents">
Agora os traces dos seus agentes crewAI estão sendo capturados pelo MLflow.
Vamos acessar o servidor de tracking do MLflow para visualizar os traces e obter insights dos seus Agents.
Abra `127.0.0.1:5000` em seu navegador para acessar o servidor de tracking do MLflow.
<Frame caption="Painel de Tracing do MLflow">
<img src="/images/mlflow1.png" alt="Exemplo de tracing do MLflow com crewai" />
</Frame>
</Step>
</Steps>

180
docs/pt-BR/observability/openlit.mdx Normal file
View File

@@ -0,0 +1,180 @@
---
title: Integração OpenLIT
description: Comece a monitorar seus Agentes rapidamente com apenas uma linha de código usando OpenTelemetry.
icon: magnifying-glass-chart
---
# Visão Geral do OpenLIT
[OpenLIT](https://github.com/openlit/openlit?src=crewai-docs) é uma ferramenta open-source que simplifica o monitoramento de desempenho de agentes de IA, LLMs, VectorDBs e GPUs com apenas **uma** linha de código.
Ela oferece rastreamento e métricas nativos do OpenTelemetry para acompanhar parâmetros importantes como custo, latência, interações e sequências de tarefas.
Essa configuração permite acompanhar hiperparâmetros e monitorar problemas de desempenho, ajudando a encontrar formas de aprimorar e refinar seus agentes com o tempo.
<Frame caption="Painel do OpenLIT">
<img src="/images/openlit1.png" alt="Visão geral do uso de agentes, incluindo custo e tokens" />
<img src="/images/openlit2.png" alt="Visão geral dos rastreamentos e métricas otel do agente" />
<img src="/images/openlit3.png" alt="Visão detalhada dos rastreamentos do agente" />
</Frame>
### Funcionalidades
- **Painel Analítico**: Monitore a saúde e desempenho dos seus Agentes com dashboards detalhados que acompanham métricas, custos e interações dos usuários.
- **SDK de Observabilidade Nativo OpenTelemetry**: SDKs neutros de fornecedor para enviar rastreamentos e métricas para suas ferramentas de observabilidade existentes como Grafana, DataDog e outros.
- **Rastreamento de Custos para Modelos Customizados e Ajustados**: Adapte estimativas de custo para modelos específicos usando arquivos de precificação customizados para orçamentos precisos.
- **Painel de Monitoramento de Exceções**: Identifique e solucione rapidamente problemas ao rastrear exceções comuns e erros por meio de um painel de monitoramento.
- **Conformidade e Segurança**: Detecte ameaças potenciais como profanidade e vazamento de dados sensíveis (PII).
- **Detecção de Prompt Injection**: Identifique possíveis injeções de código e vazamentos de segredos.
- **Gerenciamento de Chaves de API e Segredos**: Gerencie suas chaves de API e segredos do LLM de forma centralizada e segura, evitando práticas inseguras.
- **Gerenciamento de Prompt**: Gerencie e versiona prompts de Agente usando o PromptHub para acesso consistente e fácil entre os agentes.
- **Model Playground** Teste e compare diferentes modelos para seus agentes CrewAI antes da implantação.
## Instruções de Configuração
<Steps>
<Step title="Implantar o OpenLIT">
<Steps>
<Step title="Clonar o Repositório do OpenLIT">
```shell
git clone git@github.com:openlit/openlit.git
```
</Step>
<Step title="Iniciar o Docker Compose">
A partir do diretório raiz do [Repositório OpenLIT](https://github.com/openlit/openlit), execute o comando abaixo:
```shell
docker compose up -d
```
</Step>
</Steps>
</Step>
<Step title="Instalar o SDK OpenLIT">
```shell
pip install openlit
```
</Step>
<Step title="Inicializar o OpenLIT em Sua Aplicação">
Adicione as duas linhas abaixo ao seu código de aplicação:
<Tabs>
<Tab title="Configuração usando argumentos de função">
```python
import openlit
openlit.init(otlp_endpoint="http://127.0.0.1:4318")
```
Exemplo de uso para monitoramento de um Agente CrewAI:
```python
from crewai import Agent, Task, Crew, Process
import openlit
openlit.init(disable_metrics=True)
# Definir seus agentes
researcher = Agent(
role="Researcher",
goal="Conduct thorough research and analysis on AI and AI agents",
backstory="You're an expert researcher, specialized in technology, software engineering, AI, and startups. You work as a freelancer and are currently researching for a new client.",
allow_delegation=False,
llm='command-r'
)
# Definir sua task
task = Task(
description="Generate a list of 5 interesting ideas for an article, then write one captivating paragraph for each idea that showcases the potential of a full article on this topic. Return the list of ideas with their paragraphs and your notes.",
expected_output="5 bullet points, each with a paragraph and accompanying notes.",
)
# Definir o agente gerente
manager = Agent(
role="Project Manager",
goal="Efficiently manage the crew and ensure high-quality task completion",
backstory="You're an experienced project manager, skilled in overseeing complex projects and guiding teams to success. Your role is to coordinate the efforts of the crew members, ensuring that each task is completed on time and to the highest standard.",
allow_delegation=True,
llm='command-r'
)
# Instanciar sua crew com um manager personalizado
crew = Crew(
agents=[researcher],
tasks=[task],
manager_agent=manager,
process=Process.hierarchical,
)
# Iniciar o trabalho da crew
result = crew.kickoff()
print(result)
```
</Tab>
<Tab title="Configuração usando Variáveis de Ambiente">
Adicione as duas linhas abaixo ao seu código de aplicação:
```python
import openlit
openlit.init()
```
Execute o seguinte comando para configurar o endpoint de exportação OTEL:
```shell
export OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4318"
```
Exemplo de uso para monitoramento de um Agente CrewAI Async:
```python
import asyncio
from crewai import Crew, Agent, Task
import openlit
openlit.init(otlp_endpoint="http://127.0.0.1:4318")
# Criar um agente com execução de código habilitada
coding_agent = Agent(
role="Python Data Analyst",
goal="Analyze data and provide insights using Python",
backstory="You are an experienced data analyst with strong Python skills.",
allow_code_execution=True,
llm="command-r"
)
# Criar uma task que exige execução de código
data_analysis_task = Task(
description="Analyze the given dataset and calculate the average age of participants. Ages: {ages}",
agent=coding_agent,
expected_output="5 bullet points, each with a paragraph and accompanying notes.",
)
# Criar uma crew e adicionar a task
analysis_crew = Crew(
agents=[coding_agent],
tasks=[data_analysis_task]
)
# Função async para iniciar a crew de forma assíncrona
async def async_crew_execution():
result = await analysis_crew.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]})
print("Crew Result:", result)
# Executar a função async
asyncio.run(async_crew_execution())
```
</Tab>
</Tabs>
Consulte o [repositório do SDK Python do OpenLIT](https://github.com/openlit/openlit/tree/main/sdk/python) para configurações e casos de uso avançados.
</Step>
<Step title="Visualizar e Analisar">
Com os dados de Observabilidade dos Agentes agora sendo coletados e enviados ao OpenLIT, o próximo passo é visualizar e analisar esses dados para obter insights sobre o desempenho, comportamento e identificar oportunidades de melhoria dos seus Agentes.
Basta acessar o OpenLIT em `127.0.0.1:3000` no seu navegador para começar a explorar. Você pode fazer login usando as credenciais padrão
- **Email**: `user@openlit.io`
- **Senha**: `openlituser`
<Frame caption="Painel do OpenLIT">
<img src="/images/openlit1.png" alt="Visão geral do uso de agentes, incluindo custo e tokens" />
<img src="/images/openlit2.png" alt="Visão geral dos rastreamentos e métricas otel do agente" />
</Frame>
</Step>
</Steps>

Some files were not shown because too many files have changed in this diff Show More