mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-07-09 00:45:16 +00:00
feat: adopt directory-based docs versioning with Edge channel
Switch docs.crewai.com from navigation-only versioning (every version selector entry rendered the same docs/<lang>/* source files) to Mintlify's directory-based versioning so each version selector entry renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/* that always reflects main HEAD for unreleased work, eliminating pre-release leakage onto frozen release labels. External links to canonical /<lang>/* URLs are preserved via wildcard redirects that always land on the current default version. Layout: - docs/edge/<lang>/* rolling source (you edit here) - docs/edge/enterprise-api.*.yaml - docs/v<X.Y.Z>/<lang>/* frozen, immutable snapshots - docs/v<X.Y.Z>/enterprise-api.*.yaml - docs/images/ shared, append-only - docs/docs.json nav + redirects URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links working, and every freeze rewrites them (plus all per-section/per-page redirects) so destinations always resolve to the current default without depending on a second redirect hop. Release flow integration (devtools release): - New module crewai_devtools.docs_versioning.freeze() materialises docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the snapshot, inserts the version into every language block in docs.json, and refreshes all redirect destinations. - _update_docs_and_create_pr() in cli.py now calls that freeze during Phase 2 of devtools release. Edge changelogs are updated first (so the snapshot freeze picks them up), then the snapshot is staged alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z> — the title prefix the new CI guard reads. - The PR still gates tag, GitHub release, PyPI publish, and the enterprise release as before; no new PRs are added. - Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride Edge — and the docs PR title omits the [docs-freeze] prefix. - docs_check (AI-generated docs scaffolding) writes to docs/edge/<lang>/* so newly-generated unreleased docs land in Edge and never accidentally touch a frozen snapshot. Migration scripts (one-shot): - scripts/docs/freeze_historical_versions.py reconstructs all 16 historical snapshots (v1.10.0 .. v1.14.7) from git tags via git archive | tar, rewriting openapi: MDX refs so each snapshot reads its own enterprise-api YAML rather than the live one. - scripts/docs/prefix_version_paths.py one-shot-migrates docs.json: rewrites every page path in 16 versioned blocks to point under docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags v1.14.7 as Latest (default), prunes pages whose target file doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before v1.12.0), and writes the wildcard + per-section redirects. - scripts/docs/freeze_current_edge.py is now a thin CLI wrapper around docs_versioning.freeze for manual one-off freezes (e.g. retroactively snapshotting a forgotten release). CI guards (.github/workflows/docs-snapshots.yml): - Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose title contains [docs-freeze] (i.e. release-cut PRs generated by devtools release or the manual wrapper) may modify them. - Images under docs/images/ are append-only since snapshots share a single image directory. Deleting or renaming an image breaks every historical snapshot that still references it. Restored docs/images/crewai-otel-export.png from PR #3673; it was deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference it. Restoring instead of editing the snapshots preserves historical rendering fidelity and validates the new append-only rule retroactively. Tests: - lib/devtools/tests/test_docs_versioning.py covers the freeze: file copy, openapi rewrite, version insertion, default demotion, redirect upserts, per-section redirect rewriting, idempotency, and invalid inputs. Verified locally with mintlify broken-links: 0 broken links across the full site (Edge + 16 frozen versions, 4 locales). AGENTS.md (repo root) is the contributor guide for the new model; RELEASING.md is the release-cut runbook; README's Contribution section links to both. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Lucas Gomide
8
docs/edge/pt-BR/api-reference/inputs.mdx
Normal file
8
docs/edge/pt-BR/api-reference/inputs.mdx
Normal file
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: "GET /inputs"
|
||||
description: "Obter entradas necessárias para sua crew"
|
||||
openapi: "/enterprise-api.pt-BR.yaml GET /inputs"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
|
||||
135
docs/edge/pt-BR/api-reference/introduction.mdx
Normal file
135
docs/edge/pt-BR/api-reference/introduction.mdx
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
title: "Introdução"
|
||||
description: "Referência completa para a API REST do CrewAI AMP"
|
||||
icon: "code"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# CrewAI AMP API
|
||||
|
||||
Bem-vindo à referência da API do CrewAI AMP. 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 AMP 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 AMP.
|
||||
</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 AMP 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>
|
||||
8
docs/edge/pt-BR/api-reference/kickoff.mdx
Normal file
8
docs/edge/pt-BR/api-reference/kickoff.mdx
Normal file
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: "POST /kickoff"
|
||||
description: "Iniciar a execução da crew"
|
||||
openapi: "/enterprise-api.pt-BR.yaml POST /kickoff"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
|
||||
6
docs/edge/pt-BR/api-reference/resume.mdx
Normal file
6
docs/edge/pt-BR/api-reference/resume.mdx
Normal file
@@ -0,0 +1,6 @@
|
||||
---
|
||||
title: "POST /resume"
|
||||
description: "Retomar execução do crew com feedback humano"
|
||||
openapi: "/enterprise-api.pt-BR.yaml POST /resume"
|
||||
mode: "wide"
|
||||
---
|
||||
6
docs/edge/pt-BR/api-reference/status.mdx
Normal file
6
docs/edge/pt-BR/api-reference/status.mdx
Normal file
@@ -0,0 +1,6 @@
|
||||
---
|
||||
title: "GET /status/{kickoff_id}"
|
||||
description: "Obter o status da execução"
|
||||
openapi: "/enterprise-api.pt-BR.yaml GET /status/{kickoff_id}"
|
||||
mode: "wide"
|
||||
---
|
||||
4407
docs/edge/pt-BR/changelog.mdx
Normal file
4407
docs/edge/pt-BR/changelog.mdx
Normal file
File diff suppressed because it is too large
Load Diff
147
docs/edge/pt-BR/concepts/agent-capabilities.mdx
Normal file
147
docs/edge/pt-BR/concepts/agent-capabilities.mdx
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: "Capacidades do Agente"
|
||||
description: "Entenda as cinco formas de estender agentes CrewAI: Ferramentas, MCPs, Apps, Skills e Knowledge."
|
||||
icon: puzzle-piece
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Agentes CrewAI podem ser estendidos com **cinco tipos distintos de capacidades**, cada um servindo a um propósito diferente. Entender quando usar cada um — e como eles funcionam juntos — é fundamental para construir agentes eficazes.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Ferramentas" icon="wrench" href="/pt-BR/concepts/tools" color="#3B82F6">
|
||||
**Funções chamáveis** — permitem que agentes tomem ações. Buscas na web, operações com arquivos, chamadas de API, execução de código.
|
||||
</Card>
|
||||
<Card title="Servidores MCP" icon="plug" href="/pt-BR/mcp/overview" color="#8B5CF6">
|
||||
**Servidores de ferramentas remotos** — conectam agentes a servidores de ferramentas externos via Model Context Protocol. Mesmo efeito de ferramentas, mas hospedados externamente.
|
||||
</Card>
|
||||
<Card title="Apps" icon="grid-2" color="#EC4899">
|
||||
**Integrações com plataformas** — conectam agentes a aplicativos SaaS (Gmail, Slack, Jira, Salesforce) via plataforma CrewAI. Executa localmente com um token de integração.
|
||||
</Card>
|
||||
<Card title="Skills" icon="bolt" href="/pt-BR/concepts/skills" color="#F59E0B">
|
||||
**Expertise de domínio** — injetam instruções, diretrizes e material de referência nos prompts dos agentes. Skills dizem aos agentes *como pensar*.
|
||||
</Card>
|
||||
<Card title="Knowledge" icon="book" href="/pt-BR/concepts/knowledge" color="#10B981">
|
||||
**Fatos recuperados** — fornecem aos agentes dados de documentos, arquivos e URLs via busca semântica (RAG). Knowledge dá aos agentes *o que saber*.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
---
|
||||
|
||||
## A Distinção Fundamental
|
||||
|
||||
O mais importante a entender: **essas capacidades se dividem em duas categorias**.
|
||||
|
||||
### Capacidades de Ação (Ferramentas, MCPs, Apps)
|
||||
|
||||
Estas dão aos agentes a capacidade de **fazer coisas** — chamar APIs, ler arquivos, buscar na web, enviar emails. No momento da execução, os três tipos se resolvem no mesmo formato interno (instâncias de `BaseTool`) e aparecem em uma lista unificada de ferramentas que o agente pode chamar.
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai_tools import SerperDevTool, FileReadTool
|
||||
|
||||
agent = Agent(
|
||||
role="Researcher",
|
||||
goal="Find and compile market data",
|
||||
backstory="Expert market analyst",
|
||||
tools=[SerperDevTool(), FileReadTool()], # Ferramentas locais
|
||||
mcps=["https://mcp.example.com/sse"], # Ferramentas de servidor MCP remoto
|
||||
apps=["gmail", "google_sheets"], # Integrações com plataformas
|
||||
)
|
||||
```
|
||||
|
||||
### Capacidades de Contexto (Skills, Knowledge)
|
||||
|
||||
Estas modificam o **prompt** do agente — injetando expertise, instruções ou dados recuperados antes do agente começar a raciocinar. Não dão aos agentes novas ações; elas moldam como os agentes pensam e a quais informações têm acesso.
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
|
||||
agent = Agent(
|
||||
role="Security Auditor",
|
||||
goal="Audit cloud infrastructure for vulnerabilities",
|
||||
backstory="Expert in cloud security with 10 years of experience",
|
||||
skills=["./skills/security-audit"], # Instruções de domínio
|
||||
knowledge_sources=[pdf_source, url_source], # Fatos recuperados
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quando Usar o Quê
|
||||
|
||||
| Você precisa... | Use | Exemplo |
|
||||
| :------------------------------------------------------- | :---------------- | :--------------------------------------- |
|
||||
| Agente buscar na web | **Ferramentas** | `tools=[SerperDevTool()]` |
|
||||
| Agente chamar uma API remota via MCP | **MCPs** | `mcps=["https://api.example.com/sse"]` |
|
||||
| Agente enviar emails pelo Gmail | **Apps** | `apps=["gmail"]` |
|
||||
| Agente seguir procedimentos específicos | **Skills** | `skills=["./skills/code-review"]` |
|
||||
| Agente consultar documentos da empresa | **Knowledge** | `knowledge_sources=[pdf_source]` |
|
||||
| Agente buscar na web E seguir diretrizes de revisão | **Ferramentas + Skills** | Use ambos juntos |
|
||||
|
||||
---
|
||||
|
||||
## Combinando Capacidades
|
||||
|
||||
Na prática, agentes frequentemente usam **múltiplos tipos de capacidades juntos**. Aqui está um exemplo realista:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool
|
||||
|
||||
# Um agente de pesquisa totalmente equipado
|
||||
researcher = Agent(
|
||||
role="Senior Research Analyst",
|
||||
goal="Produce comprehensive market analysis reports",
|
||||
backstory="Expert analyst with deep industry knowledge",
|
||||
|
||||
# AÇÃO: O que o agente pode FAZER
|
||||
tools=[
|
||||
SerperDevTool(), # Buscar na web
|
||||
FileReadTool(), # Ler arquivos locais
|
||||
CodeInterpreterTool(), # Executar código Python para análise
|
||||
],
|
||||
mcps=["https://data-api.example.com/sse"], # Acessar API de dados remota
|
||||
apps=["google_sheets"], # Escrever no Google Sheets
|
||||
|
||||
# CONTEXTO: O que o agente SABE
|
||||
skills=["./skills/research-methodology"], # Como conduzir pesquisas
|
||||
knowledge_sources=[company_docs], # Dados específicos da empresa
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tabela Comparativa
|
||||
|
||||
| Característica | Ferramentas | MCPs | Apps | Skills | Knowledge |
|
||||
| :--- | :---: | :---: | :---: | :---: | :---: |
|
||||
| **Dá ações ao agente** | ✅ | ✅ | ✅ | ❌ | ❌ |
|
||||
| **Modifica o prompt** | ❌ | ❌ | ❌ | ✅ | ✅ |
|
||||
| **Requer código** | Sim | Apenas config | Apenas config | Apenas Markdown | Apenas config |
|
||||
| **Executa localmente** | Sim | Depende | Sim (com variável de ambiente) | N/A | Sim |
|
||||
| **Precisa de chaves API** | Por ferramenta | Por servidor | Token de integração | Não | Apenas embedder |
|
||||
| **Definido no Agent** | `tools=[]` | `mcps=[]` | `apps=[]` | `skills=[]` | `knowledge_sources=[]` |
|
||||
| **Definido no Crew** | ❌ | ❌ | ❌ | `skills=[]` | `knowledge_sources=[]` |
|
||||
|
||||
---
|
||||
|
||||
## Aprofundamentos
|
||||
|
||||
Pronto para aprender mais sobre cada tipo de capacidade?
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Ferramentas" icon="wrench" href="/pt-BR/concepts/tools">
|
||||
Crie ferramentas personalizadas, use o catálogo OSS com 75+ opções, configure cache e execução assíncrona.
|
||||
</Card>
|
||||
<Card title="Integração MCP" icon="plug" href="/pt-BR/mcp/overview">
|
||||
Conecte-se a servidores MCP via stdio, SSE ou HTTP. Filtre ferramentas, configure autenticação.
|
||||
</Card>
|
||||
<Card title="Skills" icon="bolt" href="/pt-BR/concepts/skills">
|
||||
Construa pacotes de skills com SKILL.md, injete expertise de domínio, use divulgação progressiva.
|
||||
</Card>
|
||||
<Card title="Knowledge" icon="book" href="/pt-BR/concepts/knowledge">
|
||||
Adicione conhecimento de PDFs, CSVs, URLs e mais. Configure embedders e recuperação.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
659
docs/edge/pt-BR/concepts/agents.mdx
Normal file
659
docs/edge/pt-BR/concepts/agents.mdx
Normal file
@@ -0,0 +1,659 @@
|
||||
---
|
||||
title: Agentes
|
||||
description: Guia detalhado sobre como criar e gerenciar agentes no framework CrewAI.
|
||||
icon: robot
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP inclui um Construtor Visual de Agentes, que simplifica a criação e configuração de agentes sem escrever código. Projete seus agentes visualmente e teste-os em tempo real.
|
||||
|
||||
|
||||
|
||||
O Construtor Visual de Agentes permite:
|
||||
|
||||
- Configuração intuitiva de agentes com interfaces baseadas em formulários
|
||||
- Testes e validação em tempo real
|
||||
- Biblioteca de modelos com tipos de agentes pré-configurados
|
||||
- Fácil personalização de atributos e comportamentos do agente
|
||||
</Note>
|
||||
|
||||
## Atributos do Agente
|
||||
|
||||
| Atributo | Parâmetro | Tipo | Descrição |
|
||||
| :-------------------------------------- | :----------------------- | :------------------------------------ | :-------------------------------------------------------------------------------------------------------- |
|
||||
| **Role (Função)** | `role` | `str` | Define a função e a área de especialização do agente dentro da equipe. |
|
||||
| **Goal (Objetivo)** | `goal` | `str` | O objetivo individual que guia a tomada de decisão do agente. |
|
||||
| **Backstory (História de fundo)** | `backstory` | `str` | Fornece contexto e personalidade ao agente, enriquecendo as interações. |
|
||||
| **LLM** _(opcional)_ | `llm` | `Union[str, LLM, Any]` | Modelo de linguagem que alimenta o agente. Padrão: modelo especificado em `OPENAI_MODEL_NAME` ou "gpt-4". |
|
||||
| **Tools (Ferramentas)** _(opcional)_ | `tools` | `List[BaseTool]` | Capacidades ou funções disponíveis para o agente. Padrão: lista vazia. |
|
||||
| **Function Calling LLM** _(opcional)_ | `function_calling_llm` | `Optional[Any]` | Modelo de linguagem usado para chamada de ferramentas, sobrescreve LLM principal se especificado. |
|
||||
| **Max Iterations** _(opcional)_ | `max_iter` | `int` | Número máximo de iterações antes do agente fornecer sua melhor resposta. Padrão: 20. |
|
||||
| **Max RPM** _(opcional)_ | `max_rpm` | `Optional[int]` | Quantidade máxima de requisições por minuto para evitar limites de taxa. |
|
||||
| **Max Execution Time** _(opcional)_ | `max_execution_time` | `Optional[int]` | Tempo máximo (em segundos) de execução da tarefa. |
|
||||
| **Verbose** _(opcional)_ | `verbose` | `bool` | Habilita logs detalhados de execução para depuração. Padrão: False. |
|
||||
| **Allow Delegation** _(opcional)_ | `allow_delegation` | `bool` | Permite que o agente delegue tarefas para outros agentes. Padrão: False. |
|
||||
| **Step Callback** _(opcional)_ | `step_callback` | `Optional[Any]` | Função chamada após cada passo do agente, sobrescreve callback da equipe. |
|
||||
| **Cache** _(opcional)_ | `cache` | `bool` | Ativa cache para o uso de ferramentas. Padrão: True. |
|
||||
| **System Template** _(opcional)_ | `system_template` | `Optional[str]` | Template personalizado de prompt de sistema para o agente. |
|
||||
| **Prompt Template** _(opcional)_ | `prompt_template` | `Optional[str]` | Template de prompt personalizado para o agente. |
|
||||
| **Response Template** _(opcional)_ | `response_template` | `Optional[str]` | Template de resposta personalizado para o agente. |
|
||||
| **Allow Code Execution** _(opcional)_ | `allow_code_execution` | `Optional[bool]` | Ativa execução de código pelo agente. Padrão: False. |
|
||||
| **Max Retry Limit** _(opcional)_ | `max_retry_limit` | `int` | Número máximo de tentativas (retries) em caso de erro. Padrão: 2. |
|
||||
| **Respect Context Window** _(opcional)_ | `respect_context_window` | `bool` | Mantém as mensagens dentro do tamanho da janela de contexto, resumindo quando necessário. Padrão: True. |
|
||||
| **Code Execution Mode** _(opcional)_ | `code_execution_mode` | `Literal["safe", "unsafe"]` | Modo de execução de código: 'safe' (usando Docker) ou 'unsafe' (direto). Padrão: 'safe'. |
|
||||
| **Multimodal** _(opcional)_ | `multimodal` | `bool` | Se o agente suporta capacidades multimodais. Padrão: False. |
|
||||
| **Inject Date** _(opcional)_ | `inject_date` | `bool` | Se deve injetar automaticamente a data atual nas tarefas. Padrão: False. |
|
||||
| **Date Format** _(opcional)_ | `date_format` | `str` | Formato de data utilizado quando `inject_date` está ativo. Padrão: "%Y-%m-%d" (formato ISO). |
|
||||
| **Reasoning** _(opcional)_ | `reasoning` | `bool` | Se o agente deve refletir e criar um plano antes de executar uma tarefa. Padrão: False. |
|
||||
| **Max Reasoning Attempts** _(opcional)_ | `max_reasoning_attempts` | `Optional[int]` | Número máximo de tentativas de raciocínio antes de executar a tarefa. Se None, tentará até estar pronto. |
|
||||
| **Embedder** _(opcional)_ | `embedder` | `Optional[Dict[str, Any]]` | Configuração do embedder utilizado pelo agente. |
|
||||
| **Knowledge Sources** _(opcional)_ | `knowledge_sources` | `Optional[List[BaseKnowledgeSource]]` | Fontes de conhecimento disponíveis para o agente. |
|
||||
| **Use System Prompt** _(opcional)_ | `use_system_prompt` | `Optional[bool]` | Se deve usar o system prompt (suporte para modelo o1). Padrão: True. |
|
||||
|
||||
## Criando Agentes
|
||||
|
||||
Existem duas formas comuns de criar agentes no CrewAI: usando **configuração JSONC (recomendado para novas crews)** ou definindo-os **diretamente em código**.
|
||||
|
||||
### Configuração JSONC (Recomendado)
|
||||
|
||||
Novos projetos criados com `crewai create crew <name>` usam configuração JSON-first. Cada agente fica em `agents/<agent_name>.jsonc`, e `crew.jsonc` lista quais agentes fazem parte da crew.
|
||||
|
||||
```jsonc agents/researcher.jsonc
|
||||
{
|
||||
"role": "{topic} Senior Data Researcher",
|
||||
"goal": "Uncover cutting-edge developments in {topic}",
|
||||
"backstory": "You find the most relevant information and present it clearly.",
|
||||
"llm": "openai/gpt-4o",
|
||||
"tools": ["SerperDevTool"],
|
||||
"settings": {
|
||||
"verbose": true,
|
||||
"allow_delegation": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use `{placeholder}` em `role`, `goal` ou `backstory`. Defina padrões em `crew.jsonc` dentro de `inputs`; `crewai run` pergunta por valores que estiverem faltando. Campos de comportamento como `verbose`, `allow_delegation`, `max_iter`, `memory`, `cache` e `planning_config` podem ficar no topo ou em `settings`.
|
||||
|
||||
<Note>
|
||||
JSONC aceita comentários e vírgulas finais. Se `agents/<name>.jsonc` e `agents/<name>.json` existirem, CrewAI usa o arquivo JSONC.
|
||||
</Note>
|
||||
|
||||
### Configuração YAML Clássica
|
||||
|
||||
Projetos clássicos criados com `crewai create crew <name> --classic` usam `config/agents.yaml` e uma classe `@CrewBase` em `crew.py`.
|
||||
|
||||
A configuração YAML continua suportada para projetos existentes em Python/YAML e para equipes que preferem definir agentes a partir de uma classe `@CrewBase`.
|
||||
|
||||
Depois de criar um projeto clássico, navegue até o arquivo `src/<project_name>/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/<project_name>/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/<project_name>/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="Cientista de Dados Sênior",
|
||||
goal="Analisar e interpretar conjuntos de dados complexos para fornecer insights acionáveis",
|
||||
backstory="Com mais de 10 anos de experiência em ciência de dados e aprendizado de máquina, você é especialista em encontrar padrões em grandes volumes de dados.",
|
||||
llm="gpt-4", # Padrão: OPENAI_MODEL_NAME ou "gpt-4"
|
||||
function_calling_llm=None, # Opcional: LLM separado para chamadas de ferramentas
|
||||
verbose=False, # Padrão: False
|
||||
allow_delegation=False, # Padrão: False
|
||||
max_iter=20, # Padrão: 20 iterações
|
||||
max_rpm=None, # Opcional: Limite de requisições por minuto
|
||||
max_execution_time=None, # Opcional: Tempo máximo de execução em segundos
|
||||
max_retry_limit=2, # Padrão: 2 tentativas em caso de erro
|
||||
allow_code_execution=False, # Padrão: False
|
||||
code_execution_mode="safe", # Padrão: "safe" (opções: "safe", "unsafe")
|
||||
respect_context_window=True, # Padrão: True
|
||||
use_system_prompt=True, # Padrão: True
|
||||
multimodal=False, # Padrão: False
|
||||
inject_date=False, # Padrão: False
|
||||
date_format="%Y-%m-%d", # Padrão: formato ISO
|
||||
reasoning=False, # Padrão: False
|
||||
max_reasoning_attempts=None, # Padrão: None
|
||||
tools=[SerperDevTool()], # Opcional: Lista de ferramentas
|
||||
knowledge_sources=None, # Opcional: Lista de fontes de conhecimento
|
||||
embedder=None, # Opcional: Configuração de embedder customizado
|
||||
system_template=None, # Opcional: Template de prompt de sistema
|
||||
prompt_template=None, # Opcional: Template de prompt customizado
|
||||
response_template=None, # Opcional: Template de resposta customizado
|
||||
step_callback=None, # Opcional: Função de callback para monitoramento
|
||||
)
|
||||
```
|
||||
|
||||
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="Analista de Pesquisa",
|
||||
goal="Encontrar e resumir informações sobre tópicos específicos",
|
||||
backstory="Você é um pesquisador experiente com atenção aos detalhes",
|
||||
tools=[SerperDevTool()],
|
||||
verbose=True # Ativa logs para depuração
|
||||
)
|
||||
```
|
||||
|
||||
#### Agente de Desenvolvimento de Código
|
||||
|
||||
```python Code
|
||||
dev_agent = Agent(
|
||||
role="Desenvolvedor Python Sênior",
|
||||
goal="Escrever e depurar códigos Python",
|
||||
backstory="Desenvolvedor Python especialista com 10 anos de experiência",
|
||||
allow_code_execution=True,
|
||||
code_execution_mode="safe", # Usa Docker para segurança
|
||||
max_execution_time=300, # Limite de 5 minutos
|
||||
max_retry_limit=3 # Mais tentativas para tarefas complexas
|
||||
)
|
||||
```
|
||||
|
||||
#### Agente de Análise de Longa Duração
|
||||
|
||||
```python Code
|
||||
analysis_agent = Agent(
|
||||
role="Analista de Dados",
|
||||
goal="Realizar análise aprofundada de grandes conjuntos de dados",
|
||||
backstory="Especialista em análise de big data e reconhecimento de padrões",
|
||||
memory=True,
|
||||
respect_context_window=True,
|
||||
max_rpm=10, # Limite de requisições por minuto
|
||||
function_calling_llm="gpt-4o-mini" # Modelo mais econômico para chamadas de ferramentas
|
||||
)
|
||||
```
|
||||
|
||||
#### Agente com Template Personalizado
|
||||
|
||||
```python Code
|
||||
custom_agent = Agent(
|
||||
role="Atendente de Suporte ao Cliente",
|
||||
goal="Auxiliar clientes com suas dúvidas e solicitações",
|
||||
backstory="Experiente em atendimento ao cliente com foco em satisfação",
|
||||
system_template="""<|start_header_id|>system<|end_header_id|>\n {{ .System }}<|eot_id|>""",
|
||||
prompt_template="""<|start_header_id|>user<|end_header_id|>\n {{ .Prompt }}<|eot_id|>""",
|
||||
response_template="""<|start_header_id|>assistant<|end_header_id|>\n {{ .Response }}<|eot_id|>""",
|
||||
)
|
||||
```
|
||||
|
||||
#### Agente Ciente de Data, com Raciocínio
|
||||
|
||||
```python Code
|
||||
strategic_agent = Agent(
|
||||
role="Analista de Mercado",
|
||||
goal="Acompanhar movimentos do mercado com referências de datas precisas e planejamento estratégico",
|
||||
backstory="Especialista em análise financeira sensível ao tempo e relatórios estratégicos",
|
||||
inject_date=True, # Injeta automaticamente a data atual nas tarefas
|
||||
date_format="%d de %B de %Y", # Exemplo: "21 de maio de 2025"
|
||||
reasoning=True, # Ativa planejamento estratégico
|
||||
max_reasoning_attempts=2, # Limite de iterações de planejamento
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
#### Agente de Raciocínio
|
||||
|
||||
```python Code
|
||||
reasoning_agent = Agent(
|
||||
role="Planejador Estratégico",
|
||||
goal="Analisar problemas complexos e criar planos de execução detalhados",
|
||||
backstory="Especialista em planejamento estratégico que desmembra desafios complexos metodicamente",
|
||||
reasoning=True, # Ativa raciocínio e planejamento
|
||||
max_reasoning_attempts=3, # Limite de tentativas de raciocínio
|
||||
max_iter=30, # Permite mais iterações para planejamento complexo
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
#### Agente Multimodal
|
||||
|
||||
```python Code
|
||||
multimodal_agent = Agent(
|
||||
role="Analista de Conteúdo Visual",
|
||||
goal="Analisar e processar tanto conteúdo textual quanto visual",
|
||||
backstory="Especialista em análise multimodal combinando compreensão de texto e imagem",
|
||||
multimodal=True, # Ativa capacidades multimodais
|
||||
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
|
||||
|
||||
<Warning>
|
||||
`allow_code_execution` e `code_execution_mode` estão depreciados. O `CodeInterpreterTool` foi removido do `crewai-tools`. Use um serviço de sandbox dedicado como [E2B](https://e2b.dev) ou [Modal](https://modal.com) para execução segura de código.
|
||||
</Warning>
|
||||
|
||||
- `allow_code_execution` _(depreciado)_: Anteriormente habilitava a execução de código embutida via `CodeInterpreterTool`.
|
||||
- `code_execution_mode` _(depreciado)_: Anteriormente controlava o modo de execução (`"safe"` para Docker, `"unsafe"` para execução direta).
|
||||
|
||||
#### 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="Pesquisador de Tecnologia em IA",
|
||||
goal="Pesquisar os últimos avanços em IA",
|
||||
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="Analista de Dados",
|
||||
goal="Analisar e memorizar padrões complexos de dados",
|
||||
memory=True, # Ativa memória
|
||||
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="Analista de Pesquisa",
|
||||
goal="Analisar grandes documentos e conjuntos de dados",
|
||||
backstory="Especialista em processar informações extensas",
|
||||
respect_context_window=True, # 🔑 Padrão: gerencia limites de contexto automaticamente
|
||||
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
|
||||
|
||||
<Warning>
|
||||
`allow_code_execution` e `code_execution_mode` estão depreciados e o `CodeInterpreterTool` foi removido. Use um serviço de sandbox dedicado como [E2B](https://e2b.dev) ou [Modal](https://modal.com) para execução segura de código.
|
||||
</Warning>
|
||||
|
||||
### 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.
|
||||
423
docs/edge/pt-BR/concepts/checkpointing.mdx
Normal file
423
docs/edge/pt-BR/concepts/checkpointing.mdx
Normal file
@@ -0,0 +1,423 @@
|
||||
---
|
||||
title: Checkpointing
|
||||
description: Salve automaticamente o estado de execução para que crews, flows e agentes possam retomar após falhas.
|
||||
icon: floppy-disk
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
O checkpointing salva um snapshot do estado de execução durante uma execução para que uma crew, flow ou agente possa retomar após uma falha ou ser bifurcado em uma branch alternativa.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Explicação" icon="lightbulb" href="#explicacao">
|
||||
Como o checkpointing funciona: eventos, armazenamento e herança.
|
||||
</Card>
|
||||
<Card title="Tutorial" icon="graduation-cap" href="#tutorial-retomar-uma-crew-com-falha">
|
||||
Um passo a passo de 5 minutos: executar, interromper, retomar.
|
||||
</Card>
|
||||
<Card title="Guias de uso" icon="screwdriver-wrench" href="#guias-de-uso">
|
||||
Receitas focadas em tarefas para fluxos comuns.
|
||||
</Card>
|
||||
<Card title="Referência" icon="book" href="#referencia">
|
||||
`CheckpointConfig`, eventos, provedores e CLI.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Explicação
|
||||
|
||||
### O que é um checkpoint
|
||||
|
||||
Um checkpoint captura tudo o que o CrewAI precisa para recriar uma execução em andamento: o estado completo da crew, flow ou agente — configuração, memória e fontes de conhecimento dos agentes, progresso das tarefas, saídas intermediárias, estado interno e atributos — junto com os inputs do kickoff, o histórico de eventos até aquele ponto e um ID de linhagem que liga o checkpoint à execução de origem.
|
||||
|
||||
Restaurar reconstrói esse estado e continua. Tarefas concluídas são puladas, memória e conhecimento são reidratados, e o trabalho downstream roda contra as mesmas saídas que a execução original produziu. Fazer fork executa a mesma restauração sob uma nova linhagem, para que a nova branch e a execução original gravem checkpoints lado a lado sem sobrescrever uma a outra.
|
||||
|
||||
### Quando os checkpoints são gravados
|
||||
|
||||
O checkpointing é orientado a eventos. O runtime se inscreve nos eventos selecionados em `on_events` e grava um checkpoint sempre que um é disparado. O padrão `task_completed` produz um checkpoint por tarefa finalizada — um equilíbrio razoável entre granularidade e uso de disco. Eventos de alta frequência como `llm_call_completed` estão disponíveis para recuperação mais granular, mas gravam muito mais arquivos.
|
||||
|
||||
### Armazenamento
|
||||
|
||||
Dois provedores acompanham o CrewAI:
|
||||
|
||||
- `JsonProvider` grava um arquivo por checkpoint. Legível e fácil de inspecionar.
|
||||
- `SqliteProvider` grava em um único banco SQLite. Melhor para checkpointing de alta frequência.
|
||||
|
||||
Ambos removem os checkpoints mais antigos quando `max_checkpoints` está definido.
|
||||
|
||||
<Note>
|
||||
Gravações de checkpoint automáticas (acionadas por evento) são best-effort: uma falha é registrada em log e a execução continua. Chamadas manuais a `state.checkpoint()` e `state.acheckpoint()` relançam a exceção.
|
||||
</Note>
|
||||
|
||||
### Modelo de herança
|
||||
|
||||
`Crew`, `Flow` e `Agent` aceitam um argumento `checkpoint`. Filhos herdam do pai a menos que definam seu próprio valor ou passem `False` para desativar. Ative o checkpointing uma vez na crew e todos os agentes participam, ou exclua um agente seletivamente.
|
||||
|
||||
## Tutorial: Retomar uma crew com falha
|
||||
|
||||
Este passo a passo leva cerca de 5 minutos. Você executará uma crew de duas tarefas, a interromperá no meio e a retomará a partir do checkpoint salvo.
|
||||
|
||||
<Steps>
|
||||
<Step title="Crie a crew com checkpointing ativado">
|
||||
```python
|
||||
from crewai import Agent, Crew, Task
|
||||
|
||||
researcher = Agent(role="Researcher", goal="Research", backstory="Expert")
|
||||
writer = Agent(role="Writer", goal="Write", backstory="Expert")
|
||||
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[
|
||||
Task(description="Research AI trends", agent=researcher, expected_output="bullets"),
|
||||
Task(description="Write a summary", agent=writer, expected_output="paragraph"),
|
||||
],
|
||||
checkpoint=True,
|
||||
)
|
||||
```
|
||||
</Step>
|
||||
<Step title="Execute e interrompa após a primeira tarefa">
|
||||
```python
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
Pressione `Ctrl+C` após a primeira tarefa concluir. Em `./.checkpoints/`, um arquivo `<timestamp>_<uuid>.json` é o checkpoint.
|
||||
</Step>
|
||||
<Step title="Retome a partir do checkpoint">
|
||||
```python
|
||||
from crewai import CheckpointConfig
|
||||
|
||||
result = crew.kickoff(
|
||||
from_checkpoint=CheckpointConfig(
|
||||
restore_from="./.checkpoints/<timestamp>_<uuid>.json",
|
||||
),
|
||||
)
|
||||
```
|
||||
|
||||
A tarefa de pesquisa é pulada, o escritor executa contra a saída de pesquisa salva e a crew finaliza.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Guias de uso
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Ativar checkpointing com padrões" icon="play">
|
||||
```python
|
||||
crew = Crew(agents=[...], tasks=[...], checkpoint=True)
|
||||
```
|
||||
|
||||
Grava em `./.checkpoints/` em cada `task_completed`.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Personalizar armazenamento e frequência" icon="sliders">
|
||||
```python
|
||||
from crewai import Crew, CheckpointConfig
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./my_checkpoints",
|
||||
on_events=["task_completed", "crew_kickoff_completed"],
|
||||
max_checkpoints=5,
|
||||
),
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Escolher um provedor de armazenamento" icon="database">
|
||||
<CodeGroup>
|
||||
```python JsonProvider
|
||||
from crewai import Crew, CheckpointConfig
|
||||
from crewai.state import JsonProvider
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./my_checkpoints",
|
||||
provider=JsonProvider(),
|
||||
max_checkpoints=5,
|
||||
),
|
||||
)
|
||||
```
|
||||
```python SqliteProvider
|
||||
from crewai import Crew, CheckpointConfig
|
||||
from crewai.state import SqliteProvider
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./.checkpoints.db",
|
||||
provider=SqliteProvider(),
|
||||
max_checkpoints=50,
|
||||
),
|
||||
)
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Tip>
|
||||
O SQLite ativa o modo journal WAL para leituras concorrentes. Prefira-o para checkpointing de alta frequência.
|
||||
</Tip>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Desativar um agente específico" icon="user-slash">
|
||||
```python
|
||||
crew = Crew(
|
||||
agents=[
|
||||
Agent(role="Researcher", ...),
|
||||
Agent(role="Writer", ..., checkpoint=False),
|
||||
],
|
||||
tasks=[...],
|
||||
checkpoint=True,
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Fazer fork em uma nova branch" icon="code-branch">
|
||||
`fork()` restaura um checkpoint sob uma nova linhagem para que a nova execução não colida com a original.
|
||||
|
||||
```python
|
||||
config = CheckpointConfig(restore_from="./my_checkpoints/<file>.json")
|
||||
crew = Crew.fork(config, branch="experiment-a")
|
||||
result = crew.kickoff(inputs={"strategy": "aggressive"})
|
||||
```
|
||||
|
||||
O label `branch` é opcional; um é gerado se omitido.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Checkpoint em Crew, Flow ou Agent" icon="cubes">
|
||||
<Tabs>
|
||||
<Tab title="Crew">
|
||||
```python
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, write_task, review_task],
|
||||
checkpoint=CheckpointConfig(location="./crew_cp"),
|
||||
)
|
||||
```
|
||||
|
||||
Gatilho padrão: `task_completed`.
|
||||
</Tab>
|
||||
<Tab title="Flow">
|
||||
```python
|
||||
from crewai.flow.flow import Flow, start, listen
|
||||
from crewai import CheckpointConfig
|
||||
|
||||
class MyFlow(Flow):
|
||||
@start()
|
||||
def step_one(self):
|
||||
return "data"
|
||||
|
||||
@listen(step_one)
|
||||
def step_two(self, data):
|
||||
return process(data)
|
||||
|
||||
flow = MyFlow(
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./flow_cp",
|
||||
on_events=["method_execution_finished"],
|
||||
),
|
||||
)
|
||||
result = flow.kickoff()
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Agent">
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Researcher",
|
||||
goal="Research topics",
|
||||
backstory="Expert researcher",
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./agent_cp",
|
||||
on_events=["lite_agent_execution_completed"],
|
||||
),
|
||||
)
|
||||
result = agent.kickoff(messages=[{"role": "user", "content": "Research AI trends"}])
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Gravar um checkpoint manualmente" icon="code">
|
||||
Registre um handler em qualquer evento e chame `state.checkpoint()`.
|
||||
|
||||
<CodeGroup>
|
||||
```python Sync
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
from crewai.events.event_bus import crewai_event_bus
|
||||
from crewai.events.types.llm_events import LLMCallCompletedEvent
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from crewai.state.runtime import RuntimeState
|
||||
|
||||
|
||||
@crewai_event_bus.on(LLMCallCompletedEvent)
|
||||
def on_llm_done(source: Any, event: LLMCallCompletedEvent, state: RuntimeState) -> None:
|
||||
path = state.checkpoint("./my_checkpoints")
|
||||
print(f"Checkpoint salvo: {path}")
|
||||
```
|
||||
```python Async
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
from crewai.events.event_bus import crewai_event_bus
|
||||
from crewai.events.types.llm_events import LLMCallCompletedEvent
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from crewai.state.runtime import RuntimeState
|
||||
|
||||
|
||||
@crewai_event_bus.on(LLMCallCompletedEvent)
|
||||
async def on_llm_done_async(source: Any, event: LLMCallCompletedEvent, state: RuntimeState) -> None:
|
||||
path = await state.acheckpoint("./my_checkpoints")
|
||||
print(f"Checkpoint salvo: {path}")
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Um argumento `state` é fornecido automaticamente quando o handler recebe três parâmetros. Veja [Event Listeners](/pt-BR/concepts/event-listener) para o catálogo completo de eventos.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Navegar, retomar e fazer fork pela CLI" icon="terminal">
|
||||
```bash
|
||||
crewai checkpoint
|
||||
crewai checkpoint --location ./my_checkpoints
|
||||
crewai checkpoint --location ./.checkpoints.db
|
||||
```
|
||||
|
||||
<Frame caption="Árvore de checkpoints — branches e forks aninham sob seu pai.">
|
||||
<img src="/images/checkpoint-tui-tree.png" alt="Checkpoint TUI tree view" />
|
||||
</Frame>
|
||||
|
||||
O painel esquerdo agrupa checkpoints por branch; forks aninham sob seu pai. Selecionar um checkpoint abre o painel de detalhes com metadados, estado da entidade e progresso das tarefas. **Resume** continua a execução; **Fork** inicia uma nova branch.
|
||||
|
||||
<Frame caption="Aba de visão geral — metadados, estado da entidade e resumo da execução.">
|
||||
<img src="/images/checkpoint-tui-detail-overview.png" alt="Checkpoint detail overview tab" />
|
||||
</Frame>
|
||||
|
||||
O painel de detalhes expõe duas áreas editáveis:
|
||||
|
||||
- **Inputs** — os inputs originais do kickoff, preenchidos e editáveis.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/checkpoint-tui-detail-inputs.png" alt="Editable kickoff inputs" />
|
||||
</Frame>
|
||||
|
||||
- **Saídas das tarefas** — saídas das tarefas concluídas. Editar uma saída e pressionar **Fork** invalida tarefas downstream para que sejam reexecutadas com o contexto modificado.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/checkpoint-tui-detail-tasks.png" alt="Editable task outputs" />
|
||||
</Frame>
|
||||
|
||||
<Frame caption="Tela de fork — confirme uma nova branch a partir do checkpoint selecionado.">
|
||||
<img src="/images/checkpoint-tui-details-fork.png" alt="Fork confirmation panel" />
|
||||
</Frame>
|
||||
|
||||
<Tip>
|
||||
Útil para exploração de cenários: fork, ajuste, observe.
|
||||
</Tip>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Inspecionar checkpoints sem a TUI" icon="magnifying-glass">
|
||||
```bash
|
||||
crewai checkpoint list ./my_checkpoints
|
||||
crewai checkpoint info ./my_checkpoints/<file>.json
|
||||
crewai checkpoint info ./.checkpoints.db
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Referência
|
||||
|
||||
### `CheckpointConfig`
|
||||
|
||||
<ParamField path="location" type="str" default='"./.checkpoints"'>
|
||||
Destino do armazenamento. Diretório para `JsonProvider`, caminho de arquivo de banco para `SqliteProvider`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="on_events" type='list[CheckpointEventType | Literal["*"]]' default='["task_completed"]'>
|
||||
Tipos de evento que disparam um checkpoint. `CheckpointEventType` é um `Literal` — seu type checker autocompleta e rejeita valores não suportados. Veja [tipos de evento](#tipos-de-evento) para a lista completa.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="provider" type="BaseProvider" default="JsonProvider()">
|
||||
Backend de armazenamento. `JsonProvider` ou `SqliteProvider`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="max_checkpoints" type="int | None" default="None">
|
||||
Máximo de checkpoints a reter. Os mais antigos são removidos após cada gravação.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="restore_from" type="Path | str | None" default="None">
|
||||
Checkpoint a restaurar quando passado via `from_checkpoint`.
|
||||
</ParamField>
|
||||
|
||||
### Valores do campo `checkpoint`
|
||||
|
||||
Aceito por `Crew`, `Flow` e `Agent`.
|
||||
|
||||
<ParamField path="None" type="padrão">
|
||||
Herda do pai.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="True" type="bool">
|
||||
Ativa com padrões.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="False" type="bool">
|
||||
Desativação explícita. Interrompe a herança.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="CheckpointConfig(...)" type="CheckpointConfig">
|
||||
Configuração personalizada.
|
||||
</ParamField>
|
||||
|
||||
### Tipos de evento
|
||||
|
||||
`on_events` aceita qualquer combinação de valores `CheckpointEventType`. O padrão `["task_completed"]` grava um checkpoint por tarefa finalizada; `["*"]` corresponde a todos os eventos.
|
||||
|
||||
<Warning>
|
||||
`["*"]` e eventos de alta frequência como `llm_call_completed` gravam muitos checkpoints e podem degradar o desempenho. Combine com `max_checkpoints`.
|
||||
</Warning>
|
||||
|
||||
<Expandable title="Todos os eventos suportados">
|
||||
|
||||
- **Task** — `task_started`, `task_completed`, `task_failed`, `task_evaluation`
|
||||
- **Crew** — `crew_kickoff_started`, `crew_kickoff_completed`, `crew_kickoff_failed`, `crew_train_started`, `crew_train_completed`, `crew_train_failed`, `crew_test_started`, `crew_test_completed`, `crew_test_failed`, `crew_test_result`
|
||||
- **Agent** — `agent_execution_started`, `agent_execution_completed`, `agent_execution_error`, `lite_agent_execution_started`, `lite_agent_execution_completed`, `lite_agent_execution_error`, `agent_evaluation_started`, `agent_evaluation_completed`, `agent_evaluation_failed`
|
||||
- **Flow** — `flow_created`, `flow_started`, `flow_finished`, `flow_paused`, `method_execution_started`, `method_execution_finished`, `method_execution_failed`, `method_execution_paused`, `human_feedback_requested`, `human_feedback_received`, `flow_input_requested`, `flow_input_received`
|
||||
- **LLM** — `llm_call_started`, `llm_call_completed`, `llm_call_failed`, `llm_stream_chunk`, `llm_thinking_chunk`
|
||||
- **LLM Guardrail** — `llm_guardrail_started`, `llm_guardrail_completed`, `llm_guardrail_failed`
|
||||
- **Tool** — `tool_usage_started`, `tool_usage_finished`, `tool_usage_error`, `tool_validate_input_error`, `tool_selection_error`, `tool_execution_error`
|
||||
- **Memory** — `memory_save_started`, `memory_save_completed`, `memory_save_failed`, `memory_query_started`, `memory_query_completed`, `memory_query_failed`, `memory_retrieval_started`, `memory_retrieval_completed`, `memory_retrieval_failed`
|
||||
- **Knowledge** — `knowledge_search_query_started`, `knowledge_search_query_completed`, `knowledge_query_started`, `knowledge_query_completed`, `knowledge_query_failed`, `knowledge_search_query_failed`
|
||||
- **Reasoning** — `agent_reasoning_started`, `agent_reasoning_completed`, `agent_reasoning_failed`
|
||||
- **MCP** — `mcp_connection_started`, `mcp_connection_completed`, `mcp_connection_failed`, `mcp_tool_execution_started`, `mcp_tool_execution_completed`, `mcp_tool_execution_failed`, `mcp_config_fetch_failed`
|
||||
- **Observation** — `step_observation_started`, `step_observation_completed`, `step_observation_failed`, `plan_refinement`, `plan_replan_triggered`, `goal_achieved_early`
|
||||
- **Skill** — `skill_discovery_started`, `skill_discovery_completed`, `skill_loaded`, `skill_activated`, `skill_load_failed`
|
||||
- **Logging** — `agent_logs_started`, `agent_logs_execution`
|
||||
- **A2A** — `a2a_delegation_started`, `a2a_delegation_completed`, `a2a_conversation_started`, `a2a_conversation_completed`, `a2a_message_sent`, `a2a_response_received`, `a2a_polling_started`, `a2a_polling_status`, `a2a_push_notification_registered`, `a2a_push_notification_received`, `a2a_push_notification_sent`, `a2a_push_notification_timeout`, `a2a_streaming_started`, `a2a_streaming_chunk`, `a2a_agent_card_fetched`, `a2a_authentication_failed`, `a2a_artifact_received`, `a2a_connection_error`, `a2a_server_task_started`, `a2a_server_task_completed`, `a2a_server_task_canceled`, `a2a_server_task_failed`, `a2a_parallel_delegation_started`, `a2a_parallel_delegation_completed`, `a2a_transport_negotiated`, `a2a_content_type_negotiated`, `a2a_context_created`, `a2a_context_expired`, `a2a_context_idle`, `a2a_context_completed`, `a2a_context_pruned`
|
||||
- **Sinais de sistema** — `SIGTERM`, `SIGINT`, `SIGHUP`, `SIGTSTP`, `SIGCONT`
|
||||
- **Wildcard** — `"*"` corresponde a todos os eventos.
|
||||
|
||||
</Expandable>
|
||||
|
||||
### Provedores de armazenamento
|
||||
|
||||
<ParamField path="JsonProvider" type="provider">
|
||||
Um arquivo por checkpoint, nomeado `<timestamp>_<uuid>.json` dentro de `location`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="SqliteProvider" type="provider">
|
||||
Arquivo de banco único em `location` com journaling WAL.
|
||||
</ParamField>
|
||||
|
||||
### CLI
|
||||
|
||||
| Comando | Propósito |
|
||||
|:--------|:----------|
|
||||
| `crewai checkpoint` | Inicia a TUI; detecta o armazenamento automaticamente. |
|
||||
| `crewai checkpoint --location <path>` | Inicia a TUI em uma localização específica. |
|
||||
| `crewai checkpoint list <path>` | Lista checkpoints. |
|
||||
| `crewai checkpoint info <path>` | Inspeciona um arquivo de checkpoint ou a entrada mais recente em um banco SQLite. |
|
||||
464
docs/edge/pt-BR/concepts/cli.mdx
Normal file
464
docs/edge/pt-BR/concepts/cli.mdx
Normal file
@@ -0,0 +1,464 @@
|
||||
---
|
||||
title: CLI
|
||||
description: Aprenda a usar o CLI do CrewAI para interagir com o CrewAI.
|
||||
icon: terminal
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Warning>
|
||||
A partir da versão 0.140.0, a plataforma CrewAI AMP iniciou um processo de
|
||||
migração de seu provedor de login. Como resultado, o fluxo de autenticação via
|
||||
CLI foi atualizado. Usuários que utlizam o Google para fazer login, ou que
|
||||
criaram conta após 3 de julho de 2025 não poderão fazer login com versões
|
||||
anteriores da biblioteca `crewai`.
|
||||
</Warning>
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
Por padrão, `crewai create crew` cria um projeto JSON-first com `crew.jsonc` e `agents/*.jsonc`. Use `crewai create crew my_new_crew --classic` somente quando quiser o scaffold antigo em Python/YAML com `crew.py`, `config/agents.yaml` e `config/tasks.yaml`.
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
```python
|
||||
# Exemplo de uso programático do comando train
|
||||
n_iterations = 2
|
||||
inputs = {"topic": "Treinamento CrewAI"}
|
||||
filename = "seu_modelo.pkl"
|
||||
|
||||
try:
|
||||
SuaCrew().crew().train(
|
||||
n_iterations=n_iterations,
|
||||
inputs=inputs,
|
||||
filename=filename
|
||||
)
|
||||
except Exception as e:
|
||||
raise Exception(f"Ocorreu um erro ao treinar a crew: {e}")
|
||||
```
|
||||
|
||||
### 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` na definição da sua crew para habilitar este comando.
|
||||
|
||||
Para crews JSON-first, adicione em `crew.jsonc`:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"name": "My Crew",
|
||||
"agents": ["researcher"],
|
||||
"tasks": [],
|
||||
"chat_llm": "openai/gpt-4o"
|
||||
}
|
||||
```
|
||||
|
||||
Para crews clássicas Python/YAML, defina em `crew.py`:
|
||||
|
||||
```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 AMP](https://app.crewai.com).
|
||||
|
||||
- **Autenticação**: Você precisa estar autenticado para implementar no CrewAI AMP.
|
||||
Você pode fazer login ou criar uma conta 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 AMP.
|
||||
|
||||
```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 AMP 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 AMP.
|
||||
|
||||
```shell Terminal
|
||||
crewai deploy push
|
||||
```
|
||||
|
||||
- Inicia o processo de deployment na plataforma CrewAI AMP.
|
||||
- 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 AMP.
|
||||
|
||||
- **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 AMP](http://app.crewai.com) usando o CLI.
|
||||
|
||||
<iframe
|
||||
className="w-full aspect-video rounded-xl"
|
||||
src="https://www.youtube.com/embed/3EqSV-CYDZA"
|
||||
title="CrewAI Deployment Guide"
|
||||
frameBorder="0"
|
||||
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 mostrará provedores de LLM disponíveis e depois a seleção de modelo para o provedor escolhido. O modelo selecionado é salvo no `.env` gerado, e cada agente JSONC pode definir seu próprio `llm`.
|
||||
|
||||
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)
|
||||
|
||||
### 12. Gerenciamento de Configuração
|
||||
|
||||
Gerencie as configurações do CLI para CrewAI.
|
||||
|
||||
```shell Terminal
|
||||
crewai config [COMANDO] [OPÇÕES]
|
||||
```
|
||||
|
||||
#### Comandos:
|
||||
|
||||
- `list`: Exibir todos os parâmetros de configuração do CLI
|
||||
|
||||
```shell Terminal
|
||||
crewai config list
|
||||
```
|
||||
|
||||
- `set`: Definir um parâmetro de configuração do CLI
|
||||
|
||||
```shell Terminal
|
||||
crewai config set <chave> <valor>
|
||||
```
|
||||
|
||||
- `reset`: Redefinir todos os parâmetros de configuração do CLI para valores padrão
|
||||
|
||||
```shell Terminal
|
||||
crewai config reset
|
||||
```
|
||||
|
||||
#### Parâmetros de Configuração Disponíveis
|
||||
|
||||
- `enterprise_base_url`: URL base da instância CrewAI AMP
|
||||
- `oauth2_provider`: Provedor OAuth2 usado para autenticação (ex: workos, okta, auth0)
|
||||
- `oauth2_audience`: Valor de audiência OAuth2, tipicamente usado para identificar a API ou recurso de destino
|
||||
- `oauth2_client_id`: ID do cliente OAuth2 emitido pelo provedor, usado durante solicitações de autenticação
|
||||
- `oauth2_domain`: Domínio do provedor OAuth2 (ex: sua-org.auth0.com) usado para emissão de tokens
|
||||
|
||||
#### Exemplos
|
||||
|
||||
Exibir configuração atual:
|
||||
|
||||
```shell Terminal
|
||||
crewai config list
|
||||
```
|
||||
|
||||
Exemplo de saída:
|
||||
|
||||
| Parâmetro | Valor | Descrição |
|
||||
| :------------------ | :--------------------- | :------------------------------------------------------------- |
|
||||
| enterprise_base_url | https://app.crewai.com | URL base da instância CrewAI AMP |
|
||||
| org_name | Not set | Nome da organização atualmente ativa |
|
||||
| org_uuid | Not set | UUID da organização atualmente ativa |
|
||||
| oauth2_provider | workos | Provedor OAuth2 (ex.: workos, okta, auth0) |
|
||||
| oauth2_audience | client_01YYY | Audience usada para identificar a API/recurso de destino |
|
||||
| oauth2_client_id | client_01XXX | Client ID OAuth2 emitido pelo provedor (usado na autenticação) |
|
||||
| oauth2_domain | login.crewai.com | Domínio do provedor OAuth2 (ex.: your-org.auth0.com) |
|
||||
|
||||
Definir a URL base do enterprise:
|
||||
|
||||
```shell Terminal
|
||||
crewai config set enterprise_base_url https://minha-empresa.crewai.com
|
||||
```
|
||||
|
||||
Definir provedor OAuth2:
|
||||
|
||||
```shell Terminal
|
||||
crewai config set oauth2_provider auth0
|
||||
```
|
||||
|
||||
Definir domínio OAuth2:
|
||||
|
||||
```shell Terminal
|
||||
crewai config set oauth2_domain minha-empresa.auth0.com
|
||||
```
|
||||
|
||||
Redefinir todas as configurações para padrões:
|
||||
|
||||
```shell Terminal
|
||||
crewai config reset
|
||||
```
|
||||
|
||||
<Note>
|
||||
As configurações são armazenadas em `~/.config/crewai/settings.json`. Algumas
|
||||
configurações como nome da organização e UUID são somente leitura e
|
||||
gerenciadas através de comandos de autenticação e organização. Configurações
|
||||
relacionadas ao repositório de ferramentas são ocultas e não podem ser
|
||||
definidas diretamente pelo usuário.
|
||||
</Note>
|
||||
361
docs/edge/pt-BR/concepts/collaboration.mdx
Normal file
361
docs/edge/pt-BR/concepts/collaboration.mdx
Normal file
@@ -0,0 +1,361 @@
|
||||
---
|
||||
title: Colaboração
|
||||
description: Como permitir que agentes trabalhem juntos, deleguem tarefas e se comuniquem de forma eficaz em equipes CrewAI.
|
||||
icon: screen-users
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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="Especialista em Pesquisa",
|
||||
goal="Realizar pesquisas aprofundadas sobre qualquer tema",
|
||||
backstory="Pesquisador especialista com acesso a diversas fontes",
|
||||
allow_delegation=True, # 🔑 Configuração chave para colaboração
|
||||
verbose=True
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role="Redator de Conteúdo",
|
||||
goal="Criar conteúdo envolvente com base em pesquisas",
|
||||
backstory="Redator habilidoso que transforma pesquisas em conteúdo atraente",
|
||||
allow_delegation=True, # 🔑 Permite fazer perguntas a outros agentes
|
||||
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="Especialista em Pesquisa",
|
||||
goal="Realizar pesquisas aprofundadas sobre qualquer tema",
|
||||
backstory="Pesquisador especialista com acesso a diversas fontes",
|
||||
allow_delegation=True,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role="Redator de Conteúdo",
|
||||
goal="Criar conteúdo envolvente com base em pesquisas",
|
||||
backstory="Redator habilidoso que transforma pesquisas em conteúdo atraente",
|
||||
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="""Escreva um artigo abrangente de 1000 palavras sobre 'O Futuro da IA na Saúde'.
|
||||
|
||||
O artigo deve incluir:
|
||||
- Aplicações atuais de IA na saúde
|
||||
- Tendências e tecnologias emergentes
|
||||
- Desafios potenciais e considerações éticas
|
||||
- Previsões de especialistas para os próximos 5 anos
|
||||
|
||||
Colabore com seus colegas para garantir precisão e qualidade.""",
|
||||
expected_output="Um artigo bem pesquisado, envolvente, com 1000 palavras, estrutura adequada e citações",
|
||||
agent=writer # O redator lidera, mas pode delegar pesquisa ao pesquisador
|
||||
)
|
||||
|
||||
# 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="Pesquise os últimos avanços em computação quântica",
|
||||
expected_output="Resumo abrangente da pesquisa com principais descobertas e fontes",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
writing_task = Task(
|
||||
description="Escreva um artigo com base nos achados da pesquisa",
|
||||
expected_output="Artigo envolvente de 800 palavras sobre computação quântica",
|
||||
agent=writer,
|
||||
context=[research_task] # Recebe a saída da pesquisa como contexto
|
||||
)
|
||||
|
||||
editing_task = Task(
|
||||
description="Edite e revise o artigo para publicação",
|
||||
expected_output="Artigo pronto para publicação, com clareza e fluidez aprimoradas",
|
||||
agent=editor,
|
||||
context=[writing_task] # Recebe o rascunho do artigo como contexto
|
||||
)
|
||||
```
|
||||
|
||||
### Padrão 2: Tarefa Única Colaborativa
|
||||
```python
|
||||
collaborative_task = Task(
|
||||
description="""Crie uma estratégia de marketing para um novo produto de IA.
|
||||
|
||||
Redator: Foque em mensagens e estratégia de conteúdo
|
||||
Pesquisador: Forneça análise de mercado e insights de concorrentes
|
||||
|
||||
Trabalhem juntos para criar uma estratégia abrangente.""",
|
||||
expected_output="Estratégia de marketing completa com embasamento em pesquisa",
|
||||
agent=writer # Agente líder, mas pode delegar ao pesquisador
|
||||
)
|
||||
```
|
||||
|
||||
## 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="Gerente de Projetos",
|
||||
goal="Coordenar esforços da equipe e garantir o sucesso do projeto",
|
||||
backstory="Gerente de projetos experiente, habilidoso em delegação e controle de qualidade",
|
||||
allow_delegation=True,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Specialist agents
|
||||
researcher = Agent(
|
||||
role="Pesquisador",
|
||||
goal="Fornecer pesquisa e análise precisas",
|
||||
backstory="Pesquisador especialista com habilidades analíticas profundas",
|
||||
allow_delegation=False, # Especialistas focam em sua expertise
|
||||
verbose=True
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role="Redator",
|
||||
goal="Criar conteúdo envolvente",
|
||||
backstory="Redator habilidoso que cria conteúdo atraente",
|
||||
allow_delegation=False,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Manager-led task
|
||||
project_task = Task(
|
||||
description="Crie um relatório de análise de mercado completo com recomendações",
|
||||
expected_output="Resumo executivo, análise detalhada e recomendações estratégicas",
|
||||
agent=manager # O gerente delega para especialistas
|
||||
)
|
||||
|
||||
# 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.
|
||||
458
docs/edge/pt-BR/concepts/crews.mdx
Normal file
458
docs/edge/pt-BR/concepts/crews.mdx
Normal file
@@ -0,0 +1,458 @@
|
||||
---
|
||||
title: Crews
|
||||
description: Compreendendo e utilizando crews no framework crewAI com atributos e funcionalidades abrangentes.
|
||||
icon: people-group
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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). | |
|
||||
| **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. |
|
||||
| **Knowledge Sources** _(opcional)_ | `knowledge_sources` | Fontes de conhecimento disponíveis no nível da crew, acessíveis a todos os agentes. |
|
||||
| **Stream** _(opcional)_ | `stream` | Habilita saída em streaming para receber atualizações em tempo real durante a execução da crew. Retorna um objeto `CrewStreamingOutput` que pode ser iterado para chunks. O padrão é `False`. |
|
||||
|
||||
<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 principais de criar crews no CrewAI: utilizando **configuração JSONC (recomendada para novas crews)** ou definindo a crew **em código** para projetos clássicos e casos avançados.
|
||||
|
||||
### Configuração JSONC (Recomendado)
|
||||
|
||||
Novos projetos criados com `crewai create crew <name>` usam `crew.jsonc` para configurações da crew e tarefas, além de um arquivo por agente em `agents/`. `crewai run` detecta `crew.jsonc` ou `crew.json`, carrega os agentes referenciados, pergunta por placeholders ausentes e inicia a crew.
|
||||
|
||||
```jsonc crew.jsonc
|
||||
{
|
||||
"name": "Market Research Crew",
|
||||
"agents": ["researcher", "analyst"],
|
||||
"tasks": [
|
||||
{
|
||||
"name": "research",
|
||||
"description": "Research {topic} and collect the most relevant facts.",
|
||||
"expected_output": "Structured research notes about {topic}.",
|
||||
"agent": "researcher"
|
||||
},
|
||||
{
|
||||
"name": "analysis",
|
||||
"description": "Analyze the research and write a concise report.",
|
||||
"expected_output": "A markdown report with findings and recommendations.",
|
||||
"agent": "analyst",
|
||||
"context": ["research"],
|
||||
"output_file": "output/report.md"
|
||||
}
|
||||
],
|
||||
"process": "sequential",
|
||||
"verbose": true,
|
||||
"memory": true,
|
||||
"inputs": {
|
||||
"topic": "AI Agents"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Cada string em `agents` resolve primeiro para `agents/<name>.jsonc` e depois para `agents/<name>.json`. Para crews hierárquicas, use `"process": "hierarchical"` com `manager_llm` ou `manager_agent`.
|
||||
|
||||
<Warning>
|
||||
Execute projetos JSON apenas de fontes confiáveis. Ferramentas `custom:<name>` e referências `{"python": "module.attribute"}` executam código Python local quando a crew é carregada.
|
||||
</Warning>
|
||||
|
||||
### Configuração YAML Clássica
|
||||
|
||||
Projetos clássicos criados com `crewai create crew <name> --classic` usam `crew.py`, `config/agents.yaml`, `config/tasks.yaml` e os decorators `@CrewBase`, `@agent`, `@task` e `@crew`.
|
||||
|
||||
Essa abordagem continua suportada para projetos existentes em Python/YAML e para equipes que precisam de controle explícito via decorators.
|
||||
|
||||
Após criar um projeto clássico, 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="Analista de Dados",
|
||||
goal="Analisar tendências de dados no mercado brasileiro",
|
||||
backstory="Analista experiente com formação em economia",
|
||||
verbose=True,
|
||||
tools=[YourCustomTool()]
|
||||
)
|
||||
|
||||
def agent_two(self) -> Agent:
|
||||
return Agent(
|
||||
role="Pesquisador de Mercado",
|
||||
goal="Coletar informações sobre a dinâmica do mercado nacional",
|
||||
backstory="Pesquisador dedicado com olhar atento aos detalhes",
|
||||
verbose=True
|
||||
)
|
||||
|
||||
def task_one(self) -> Task:
|
||||
return Task(
|
||||
description="Coletar dados recentes do mercado brasileiro e identificar tendências.",
|
||||
expected_output="Um relatório resumido com as principais tendências do mercado.",
|
||||
agent=self.agent_one()
|
||||
)
|
||||
|
||||
def task_two(self) -> Task:
|
||||
return Task(
|
||||
description="Pesquisar fatores que afetam a dinâmica do mercado nacional.",
|
||||
expected_output="Uma análise dos fatores que influenciam o mercado.",
|
||||
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.
|
||||
|
||||
#### Métodos Síncronos
|
||||
|
||||
- `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.
|
||||
|
||||
#### Métodos Assíncronos
|
||||
|
||||
O CrewAI oferece duas abordagens para execução assíncrona:
|
||||
|
||||
| Método | Tipo | Descrição |
|
||||
|--------|------|-------------|
|
||||
| `akickoff()` | Async nativo | Async/await verdadeiro em toda a cadeia de execução |
|
||||
| `akickoff_for_each()` | Async nativo | Execução async nativa para cada entrada em uma lista |
|
||||
| `kickoff_async()` | Baseado em thread | Envolve execução síncrona em `asyncio.to_thread` |
|
||||
| `kickoff_for_each_async()` | Baseado em thread | Async baseado em thread para cada entrada em uma lista |
|
||||
|
||||
<Note>
|
||||
Para cargas de trabalho de alta concorrência, `akickoff()` e `akickoff_for_each()` são recomendados pois usam async nativo para execução de tasks, operações de memória e recuperação de conhecimento.
|
||||
</Note>
|
||||
|
||||
```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 usando async nativo com akickoff
|
||||
inputs = {'topic': 'AI in healthcare'}
|
||||
async_result = await my_crew.akickoff(inputs=inputs)
|
||||
print(async_result)
|
||||
|
||||
# Exemplo usando async nativo com akickoff_for_each
|
||||
inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}]
|
||||
async_results = await my_crew.akickoff_for_each(inputs=inputs_array)
|
||||
for async_result in async_results:
|
||||
print(async_result)
|
||||
|
||||
# Exemplo usando kickoff_async baseado em thread
|
||||
inputs = {'topic': 'AI in healthcare'}
|
||||
async_result = await my_crew.kickoff_async(inputs=inputs)
|
||||
print(async_result)
|
||||
|
||||
# Exemplo usando kickoff_for_each_async baseado em thread
|
||||
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. Para exemplos detalhados de async, consulte o guia [Inicie uma Crew de Forma Assíncrona](/pt-BR/learn/kickoff-async).
|
||||
|
||||
### Streaming na Execução da Crew
|
||||
|
||||
Para visibilidade em tempo real da execução da crew, você pode habilitar streaming para receber saída conforme é gerada:
|
||||
|
||||
```python Code
|
||||
# Habilitar streaming
|
||||
crew = Crew(
|
||||
agents=[researcher],
|
||||
tasks=[task],
|
||||
stream=True
|
||||
)
|
||||
|
||||
# Iterar sobre saída em streaming
|
||||
streaming = crew.kickoff(inputs={"topic": "AI"})
|
||||
for chunk in streaming:
|
||||
print(chunk.content, end="", flush=True)
|
||||
|
||||
# Acessar resultado final
|
||||
result = streaming.result
|
||||
```
|
||||
|
||||
Saiba mais sobre streaming no guia [Streaming na Execução da Crew](/pt-BR/learn/streaming-crew-execution).
|
||||
|
||||
### 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.
|
||||
414
docs/edge/pt-BR/concepts/event-listener.mdx
Normal file
414
docs/edge/pt-BR/concepts/event-listener.mdx
Normal file
@@ -0,0 +1,414 @@
|
||||
---
|
||||
title: "Listeners de Evento"
|
||||
description: "Acesse eventos do CrewAI para criar integrações e monitoramento personalizados"
|
||||
icon: spinner
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP fornece o recurso Prompt Tracing, que aproveita o sistema de eventos para rastrear, armazenar e visualizar todos os prompts, respostas e metadados associados. Isso proporciona poderosas capacidades de depuração e transparência nas operações dos seus agentes.
|
||||
|
||||
|
||||
|
||||
Com o Prompt Tracing você pode:
|
||||
|
||||
- Visualizar o histórico completo de todos os prompts enviados ao seu LLM
|
||||
- Monitorar o uso de tokens e custos
|
||||
- Depurar falhas de raciocínio dos agentes
|
||||
- Compartilhar sequências de prompts com sua equipe
|
||||
- Comparar diferentes estratégias de prompts
|
||||
- Exportar rastreamentos para compliance e auditoria
|
||||
</Note>
|
||||
|
||||
## Criando um Listener de Evento Personalizado
|
||||
|
||||
Para criar um listener de evento personalizado, você precisa:
|
||||
|
||||
1. Criar uma classe que herde de `BaseEventListener`
|
||||
2. Implementar o método `setup_listeners`
|
||||
3. Registrar handles para os eventos de seu interesse
|
||||
4. Instanciar seu listener no arquivo apropriado
|
||||
|
||||
Veja um exemplo simples de uma classe de listener de evento personalizado:
|
||||
|
||||
```python
|
||||
from crewai.events import (
|
||||
CrewKickoffStartedEvent,
|
||||
CrewKickoffCompletedEvent,
|
||||
AgentExecutionCompletedEvent,
|
||||
)
|
||||
from crewai.events import BaseEventListener
|
||||
|
||||
class MeuListenerPersonalizado(BaseEventListener):
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
|
||||
def setup_listeners(self, crewai_event_bus):
|
||||
@crewai_event_bus.on(CrewKickoffStartedEvent)
|
||||
def ao_iniciar_crew(source, event):
|
||||
print(f"Crew '{event.crew_name}' iniciou a execução!")
|
||||
|
||||
@crewai_event_bus.on(CrewKickoffCompletedEvent)
|
||||
def ao_finalizar_crew(source, event):
|
||||
print(f"Crew '{event.crew_name}' finalizou a execução!")
|
||||
print(f"Saída: {event.output}")
|
||||
|
||||
@crewai_event_bus.on(AgentExecutionCompletedEvent)
|
||||
def ao_finalizar_execucao_agente(source, event):
|
||||
print(f"Agente '{event.agent.role}' concluiu a tarefa")
|
||||
print(f"Saída: {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.events 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...
|
||||
```
|
||||
|
||||
É assim que listeners de eventos de terceiros são registrados no código do CrewAI.
|
||||
|
||||
## 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
|
||||
- **CrewTestResultEvent**: Emitido quando um resultado de teste de Crew está disponível. Contém a pontuação de qualidade, duração da execução e modelo utilizado.
|
||||
|
||||
### 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
|
||||
- **LiteAgentExecutionStartedEvent**: Emitido quando um LiteAgent inicia a execução. Contém as informações do agente, ferramentas e mensagens.
|
||||
- **LiteAgentExecutionCompletedEvent**: Emitido quando um LiteAgent conclui a execução. Contém as informações do agente e a saída.
|
||||
- **LiteAgentExecutionErrorEvent**: Emitido quando um LiteAgent encontra um erro durante a execução. Contém as informações do agente e a mensagem de erro.
|
||||
- **AgentEvaluationStartedEvent**: Emitido quando uma avaliação de agente é iniciada. Contém o ID do agente, papel do agente, ID da tarefa opcional e número da iteração.
|
||||
- **AgentEvaluationCompletedEvent**: Emitido quando uma avaliação de agente é concluída. Contém o ID do agente, papel do agente, ID da tarefa opcional, número da iteração, categoria da métrica e pontuação.
|
||||
- **AgentEvaluationFailedEvent**: Emitido quando uma avaliação de agente falha. Contém o ID do agente, papel do agente, ID da tarefa opcional, número da iteração e mensagem de erro.
|
||||
|
||||
### 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 MCP
|
||||
|
||||
- **MCPConnectionStartedEvent**: Emitido ao iniciar a conexão com um servidor MCP. Contém o nome do servidor, URL, tipo de transporte, timeout de conexão e se é uma tentativa de reconexão.
|
||||
- **MCPConnectionCompletedEvent**: Emitido ao conectar com sucesso a um servidor MCP. Contém o nome do servidor, duração da conexão em milissegundos e se foi uma reconexão.
|
||||
- **MCPConnectionFailedEvent**: Emitido quando a conexão com um servidor MCP falha. Contém o nome do servidor, mensagem de erro e tipo de erro (`timeout`, `authentication`, `network`, etc.).
|
||||
- **MCPToolExecutionStartedEvent**: Emitido ao iniciar a execução de uma ferramenta MCP. Contém o nome do servidor, nome da ferramenta e argumentos da ferramenta.
|
||||
- **MCPToolExecutionCompletedEvent**: Emitido quando a execução de uma ferramenta MCP é concluída com sucesso. Contém o nome do servidor, nome da ferramenta, resultado e duração da execução em milissegundos.
|
||||
- **MCPToolExecutionFailedEvent**: Emitido quando a execução de uma ferramenta MCP falha. Contém o nome do servidor, nome da ferramenta, mensagem de erro e tipo de erro (`timeout`, `validation`, `server_error`, etc.).
|
||||
- **MCPConfigFetchFailedEvent**: Emitido quando a obtenção da configuração de um servidor MCP falha (ex.: o MCP não está conectado na sua conta, erro de API ou falha de conexão após a configuração ser obtida). Contém o slug, mensagem de erro e tipo de erro (`not_connected`, `api_error`, `connection_failed`).
|
||||
|
||||
### 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.
|
||||
- **LLMGuardrailFailedEvent**: Emitido quando a validação do guardrail falha. Contém a mensagem de erro e o número de tentativas.
|
||||
|
||||
### 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
|
||||
- **FlowPausedEvent**: Emitido quando um Flow é pausado aguardando feedback humano. Contém o nome do flow, ID do flow, nome do método, estado atual, mensagem exibida ao solicitar feedback e lista opcional de resultados possíveis para roteamento.
|
||||
- **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
|
||||
- **MethodExecutionPausedEvent**: Emitido quando um método do Flow é pausado aguardando feedback humano. Contém o nome do flow, nome do método, estado atual, ID do flow, mensagem exibida ao solicitar feedback e lista opcional de resultados possíveis para roteamento.
|
||||
|
||||
### Eventos de Human In The Loop
|
||||
|
||||
- **FlowInputRequestedEvent**: Emitido quando um Flow solicita entrada do usuário via `Flow.ask()`. Contém o nome do flow, nome do método, a pergunta ou prompt exibido ao usuário e metadados opcionais (ex.: ID do usuário, canal, contexto da sessão).
|
||||
- **FlowInputReceivedEvent**: Emitido quando a entrada do usuário é recebida após `Flow.ask()`. Contém o nome do flow, nome do método, a pergunta original, a resposta do usuário (ou `None` se expirou), metadados opcionais da solicitação e metadados opcionais da resposta do provedor (ex.: quem respondeu, ID do thread, timestamps).
|
||||
- **HumanFeedbackRequestedEvent**: Emitido quando um método decorado com `@human_feedback` requer entrada de um revisor humano. Contém o nome do flow, nome do método, a saída do método exibida ao humano para revisão, a mensagem exibida ao solicitar feedback e lista opcional de resultados possíveis para roteamento.
|
||||
- **HumanFeedbackReceivedEvent**: Emitido quando um humano fornece feedback em resposta a um método decorado com `@human_feedback`. Contém o nome do flow, nome do método, o texto bruto do feedback fornecido pelo humano e a string de resultado consolidada (se emit foi especificado).
|
||||
|
||||
### 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
|
||||
- **LLMThinkingChunkEvent**: Emitido quando um chunk de pensamento/raciocínio é recebido de um modelo de pensamento. Contém o texto do chunk e ID de resposta opcional.
|
||||
|
||||
### Eventos de Memória
|
||||
|
||||
- **MemoryQueryStartedEvent**: Emitido quando uma consulta de memória é iniciada. Contém a consulta, limite e threshold de pontuação opcional.
|
||||
- **MemoryQueryCompletedEvent**: Emitido quando uma consulta de memória é concluída com sucesso. Contém a consulta, resultados, limite, threshold de pontuação e tempo de execução da consulta.
|
||||
- **MemoryQueryFailedEvent**: Emitido quando uma consulta de memória falha. Contém a consulta, limite, threshold de pontuação e mensagem de erro.
|
||||
- **MemorySaveStartedEvent**: Emitido quando uma operação de salvamento de memória é iniciada. Contém o valor a ser salvo, metadados e papel do agente opcional.
|
||||
- **MemorySaveCompletedEvent**: Emitido quando uma operação de salvamento de memória é concluída com sucesso. Contém o valor salvo, metadados, papel do agente e tempo de salvamento.
|
||||
- **MemorySaveFailedEvent**: Emitido quando uma operação de salvamento de memória falha. Contém o valor, metadados, papel do agente e mensagem de erro.
|
||||
- **MemoryRetrievalStartedEvent**: Emitido quando a recuperação de memória para um prompt de tarefa é iniciada. Contém o ID da tarefa opcional.
|
||||
- **MemoryRetrievalCompletedEvent**: Emitido quando a recuperação de memória para um prompt de tarefa é concluída com sucesso. Contém o ID da tarefa, conteúdo da memória e tempo de execução da recuperação.
|
||||
- **MemoryRetrievalFailedEvent**: Emitido quando a recuperação de memória para um prompt de tarefa falha. Contém o ID da tarefa opcional e mensagem de erro.
|
||||
|
||||
### Eventos de Raciocínio
|
||||
|
||||
- **AgentReasoningStartedEvent**: Emitido quando um agente começa a raciocinar sobre uma tarefa. Contém o papel do agente, ID da tarefa e número da tentativa.
|
||||
- **AgentReasoningCompletedEvent**: Emitido quando um agente finaliza seu processo de raciocínio. Contém o papel do agente, ID da tarefa, o plano produzido e se o agente está pronto para prosseguir.
|
||||
- **AgentReasoningFailedEvent**: Emitido quando o processo de raciocínio falha. Contém o papel do agente, ID da tarefa e mensagem de erro.
|
||||
|
||||
### Eventos de Observação
|
||||
|
||||
- **StepObservationStartedEvent**: Emitido quando o Planner começa a observar o resultado de um passo. Disparado após cada execução de passo, antes da chamada LLM de observação. Contém o papel do agente, número do passo e descrição do passo.
|
||||
- **StepObservationCompletedEvent**: Emitido quando o Planner finaliza a observação do resultado de um passo. Contém se o passo foi concluído com sucesso, informações-chave aprendidas, se o plano restante ainda é válido, se é necessário um replanejamento completo e refinamentos sugeridos.
|
||||
- **StepObservationFailedEvent**: Emitido quando a chamada LLM de observação falha. O sistema continua o plano por padrão. Contém a mensagem de erro.
|
||||
- **PlanRefinementEvent**: Emitido quando o Planner refina descrições de passos futuros sem replanejamento completo. Contém o número de passos refinados e os refinamentos aplicados.
|
||||
- **PlanReplanTriggeredEvent**: Emitido quando o Planner dispara um replanejamento completo porque o plano restante foi considerado fundamentalmente incorreto. Contém o motivo do replanejamento, contagem de replanejamentos e número de passos concluídos preservados.
|
||||
- **GoalAchievedEarlyEvent**: Emitido quando o Planner detecta que o objetivo foi alcançado antecipadamente e os passos restantes serão ignorados. Contém o número de passos restantes e passos concluídos.
|
||||
|
||||
### Eventos A2A (Agent-to-Agent)
|
||||
|
||||
#### Eventos de Delegação
|
||||
|
||||
- **A2ADelegationStartedEvent**: Emitido quando a delegação A2A é iniciada. Contém a URL do endpoint, descrição da tarefa, ID do agente, ID do contexto, se é multiturn, número do turno, metadados do agent card, versão do protocolo, informações do provedor e ID da skill opcional.
|
||||
- **A2ADelegationCompletedEvent**: Emitido quando a delegação A2A é concluída. Contém o status de conclusão (`completed`, `input_required`, `failed`, etc.), resultado, mensagem de erro, ID do contexto e metadados do agent card.
|
||||
- **A2AParallelDelegationStartedEvent**: Emitido quando a delegação paralela para múltiplos agentes A2A é iniciada. Contém a lista de endpoints e a descrição da tarefa.
|
||||
- **A2AParallelDelegationCompletedEvent**: Emitido quando a delegação paralela para múltiplos agentes A2A é concluída. Contém a lista de endpoints, contagem de sucessos, contagem de falhas e resumo dos resultados.
|
||||
|
||||
#### Eventos de Conversação
|
||||
|
||||
- **A2AConversationStartedEvent**: Emitido uma vez no início de uma conversação multiturn A2A, antes da primeira troca de mensagens. Contém o ID do agente, endpoint, ID do contexto, metadados do agent card, versão do protocolo e informações do provedor.
|
||||
- **A2AMessageSentEvent**: Emitido quando uma mensagem é enviada ao agente A2A. Contém o conteúdo da mensagem, número do turno, ID do contexto, ID da mensagem e se é multiturn.
|
||||
- **A2AResponseReceivedEvent**: Emitido quando uma resposta é recebida do agente A2A. Contém o conteúdo da resposta, número do turno, ID do contexto, ID da mensagem, status e se é a resposta final.
|
||||
- **A2AConversationCompletedEvent**: Emitido uma vez ao final de uma conversação multiturn A2A. Contém o status final (`completed` ou `failed`), resultado final, mensagem de erro, ID do contexto e número total de turnos.
|
||||
|
||||
#### Eventos de Streaming
|
||||
|
||||
- **A2AStreamingStartedEvent**: Emitido quando o modo streaming é iniciado para delegação A2A. Contém o ID da tarefa, ID do contexto, endpoint, número do turno e se é multiturn.
|
||||
- **A2AStreamingChunkEvent**: Emitido quando um chunk de streaming é recebido. Contém o texto do chunk, índice do chunk, se é o chunk final, ID da tarefa, ID do contexto e número do turno.
|
||||
|
||||
#### Eventos de Polling e Push Notification
|
||||
|
||||
- **A2APollingStartedEvent**: Emitido quando o modo polling é iniciado para delegação A2A. Contém o ID da tarefa, ID do contexto, intervalo de polling em segundos e endpoint.
|
||||
- **A2APollingStatusEvent**: Emitido em cada iteração de polling. Contém o ID da tarefa, ID do contexto, estado atual da tarefa, segundos decorridos e contagem de polls.
|
||||
- **A2APushNotificationRegisteredEvent**: Emitido quando um callback de push notification é registrado. Contém o ID da tarefa, ID do contexto, URL do callback e endpoint.
|
||||
- **A2APushNotificationReceivedEvent**: Emitido quando uma push notification é recebida do agente A2A remoto. Contém o ID da tarefa, ID do contexto e estado atual.
|
||||
- **A2APushNotificationSentEvent**: Emitido quando uma push notification é enviada para uma URL de callback. Contém o ID da tarefa, ID do contexto, URL do callback, estado, se a entrega foi bem-sucedida e mensagem de erro opcional.
|
||||
- **A2APushNotificationTimeoutEvent**: Emitido quando a espera por push notification expira. Contém o ID da tarefa, ID do contexto e duração do timeout em segundos.
|
||||
|
||||
#### Eventos de Conexão e Autenticação
|
||||
|
||||
- **A2AAgentCardFetchedEvent**: Emitido quando um agent card é obtido com sucesso. Contém o endpoint, nome do agente, metadados do agent card, versão do protocolo, informações do provedor, se foi do cache e tempo de busca em milissegundos.
|
||||
- **A2AAuthenticationFailedEvent**: Emitido quando a autenticação com um agente A2A falha. Contém o endpoint, tipo de autenticação tentada (ex.: `bearer`, `oauth2`, `api_key`), mensagem de erro e código de status HTTP.
|
||||
- **A2AConnectionErrorEvent**: Emitido quando ocorre um erro de conexão durante a comunicação A2A. Contém o endpoint, mensagem de erro, tipo de erro (ex.: `timeout`, `connection_refused`, `dns_error`), código de status HTTP e a operação sendo tentada.
|
||||
- **A2ATransportNegotiatedEvent**: Emitido quando o protocolo de transporte é negociado com um agente A2A. Contém o transporte negociado, URL negociada, fonte de seleção (`client_preferred`, `server_preferred`, `fallback`) e transportes suportados pelo cliente/servidor.
|
||||
- **A2AContentTypeNegotiatedEvent**: Emitido quando os tipos de conteúdo são negociados com um agente A2A. Contém os modos de entrada/saída do cliente/servidor, modos de entrada/saída negociados e se a negociação foi bem-sucedida.
|
||||
|
||||
#### Eventos de Artefatos
|
||||
|
||||
- **A2AArtifactReceivedEvent**: Emitido quando um artefato é recebido de um agente A2A remoto. Contém o ID da tarefa, ID do artefato, nome do artefato, descrição, tipo MIME, tamanho em bytes e se o conteúdo deve ser concatenado.
|
||||
|
||||
#### Eventos de Tarefa do Servidor
|
||||
|
||||
- **A2AServerTaskStartedEvent**: Emitido quando a execução de uma tarefa do servidor A2A é iniciada. Contém o ID da tarefa e ID do contexto.
|
||||
- **A2AServerTaskCompletedEvent**: Emitido quando a execução de uma tarefa do servidor A2A é concluída. Contém o ID da tarefa, ID do contexto e resultado.
|
||||
- **A2AServerTaskCanceledEvent**: Emitido quando a execução de uma tarefa do servidor A2A é cancelada. Contém o ID da tarefa e ID do contexto.
|
||||
- **A2AServerTaskFailedEvent**: Emitido quando a execução de uma tarefa do servidor A2A falha. Contém o ID da tarefa, ID do contexto e mensagem de erro.
|
||||
|
||||
#### Eventos de Ciclo de Vida do Contexto
|
||||
|
||||
- **A2AContextCreatedEvent**: Emitido quando um contexto A2A é criado. Contextos agrupam tarefas relacionadas em uma conversação ou workflow. Contém o ID do contexto e timestamp de criação.
|
||||
- **A2AContextExpiredEvent**: Emitido quando um contexto A2A expira devido ao TTL. Contém o ID do contexto, timestamp de criação, idade em segundos e contagem de tarefas.
|
||||
- **A2AContextIdleEvent**: Emitido quando um contexto A2A fica inativo (sem atividade pelo threshold configurado). Contém o ID do contexto, tempo de inatividade em segundos e contagem de tarefas.
|
||||
- **A2AContextCompletedEvent**: Emitido quando todas as tarefas em um contexto A2A são concluídas. Contém o ID do contexto, total de tarefas e duração em segundos.
|
||||
- **A2AContextPrunedEvent**: Emitido quando um contexto A2A é podado (deletado). Contém o ID do contexto, contagem de tarefas e idade em segundos.
|
||||
|
||||
## 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`.
|
||||
|
||||
## 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.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.
|
||||
267
docs/edge/pt-BR/concepts/files.mdx
Normal file
267
docs/edge/pt-BR/concepts/files.mdx
Normal file
@@ -0,0 +1,267 @@
|
||||
---
|
||||
title: Arquivos
|
||||
description: Passe imagens, PDFs, áudio, vídeo e arquivos de texto para seus agentes para processamento multimodal.
|
||||
icon: file-image
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O CrewAI suporta entradas de arquivos multimodais nativos, permitindo que você passe imagens, PDFs, áudio, vídeo e arquivos de texto diretamente para seus agentes. Os arquivos são formatados automaticamente para os requisitos da API de cada provedor LLM.
|
||||
|
||||
<Note type="info" title="Dependência Opcional">
|
||||
O suporte a arquivos requer o pacote opcional `crewai-files`. Instale com:
|
||||
|
||||
```bash
|
||||
uv add 'crewai[file-processing]'
|
||||
```
|
||||
</Note>
|
||||
|
||||
<Note type="warning" title="Acesso Antecipado">
|
||||
A API de processamento de arquivos está atualmente em acesso antecipado.
|
||||
</Note>
|
||||
|
||||
## Tipos de Arquivo
|
||||
|
||||
O CrewAI suporta cinco tipos de arquivo específicos mais uma classe genérica `File` que detecta automaticamente o tipo:
|
||||
|
||||
| Tipo | Classe | Casos de Uso |
|
||||
|:-----|:------|:----------|
|
||||
| **Imagem** | `ImageFile` | Fotos, capturas de tela, diagramas, gráficos |
|
||||
| **PDF** | `PDFFile` | Documentos, relatórios, artigos |
|
||||
| **Áudio** | `AudioFile` | Gravações de voz, podcasts, reuniões |
|
||||
| **Vídeo** | `VideoFile` | Gravações de tela, apresentações |
|
||||
| **Texto** | `TextFile` | Arquivos de código, logs, arquivos de dados |
|
||||
| **Genérico** | `File` | Detecta automaticamente o tipo do conteúdo |
|
||||
|
||||
```python
|
||||
from crewai_files import File, ImageFile, PDFFile, AudioFile, VideoFile, TextFile
|
||||
|
||||
image = ImageFile(source="screenshot.png")
|
||||
pdf = PDFFile(source="report.pdf")
|
||||
audio = AudioFile(source="meeting.mp3")
|
||||
video = VideoFile(source="demo.mp4")
|
||||
text = TextFile(source="data.csv")
|
||||
|
||||
file = File(source="document.pdf")
|
||||
```
|
||||
|
||||
## Fontes de Arquivo
|
||||
|
||||
O parâmetro `source` aceita múltiplos tipos de entrada e detecta automaticamente o handler apropriado:
|
||||
|
||||
### De Caminho
|
||||
|
||||
```python
|
||||
from crewai_files import ImageFile
|
||||
|
||||
image = ImageFile(source="./images/chart.png")
|
||||
```
|
||||
|
||||
### De URL
|
||||
|
||||
```python
|
||||
from crewai_files import ImageFile
|
||||
|
||||
image = ImageFile(source="https://example.com/image.png")
|
||||
```
|
||||
|
||||
### De Bytes
|
||||
|
||||
```python
|
||||
from crewai_files import ImageFile, FileBytes
|
||||
|
||||
image_bytes = download_image_from_api()
|
||||
image = ImageFile(source=FileBytes(data=image_bytes, filename="downloaded.png"))
|
||||
image = ImageFile(source=image_bytes)
|
||||
```
|
||||
|
||||
## Usando Arquivos
|
||||
|
||||
Arquivos podem ser passados em múltiplos níveis, com níveis mais específicos tendo precedência.
|
||||
|
||||
### Com Crews
|
||||
|
||||
Passe arquivos ao iniciar uma crew:
|
||||
|
||||
```python
|
||||
from crewai import Crew
|
||||
from crewai_files import ImageFile
|
||||
|
||||
crew = Crew(agents=[analyst], tasks=[analysis_task])
|
||||
|
||||
result = crew.kickoff(
|
||||
inputs={"topic": "Q4 Sales"},
|
||||
input_files={
|
||||
"chart": ImageFile(source="sales_chart.png"),
|
||||
"report": PDFFile(source="quarterly_report.pdf"),
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Com Tasks
|
||||
|
||||
Anexe arquivos a tasks específicas:
|
||||
|
||||
```python
|
||||
from crewai import Task
|
||||
from crewai_files import ImageFile
|
||||
|
||||
task = Task(
|
||||
description="Analise o gráfico de vendas e identifique tendências em {chart}",
|
||||
expected_output="Um resumo das principais tendências",
|
||||
input_files={
|
||||
"chart": ImageFile(source="sales_chart.png"),
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Com Flows
|
||||
|
||||
Passe arquivos para flows, que automaticamente herdam para crews:
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, start
|
||||
from crewai_files import ImageFile
|
||||
|
||||
class AnalysisFlow(Flow):
|
||||
@start()
|
||||
def analyze(self):
|
||||
return self.analysis_crew.kickoff()
|
||||
|
||||
flow = AnalysisFlow()
|
||||
result = flow.kickoff(
|
||||
input_files={"image": ImageFile(source="data.png")}
|
||||
)
|
||||
```
|
||||
|
||||
### Com Agentes Standalone
|
||||
|
||||
Passe arquivos diretamente no kickoff do agente:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai_files import ImageFile
|
||||
|
||||
agent = Agent(
|
||||
role="Image Analyst",
|
||||
goal="Analyze images",
|
||||
backstory="Expert at visual analysis",
|
||||
llm="gpt-4o",
|
||||
)
|
||||
|
||||
result = agent.kickoff(
|
||||
messages="What's in this image?",
|
||||
input_files={"photo": ImageFile(source="photo.jpg")},
|
||||
)
|
||||
```
|
||||
|
||||
## Precedência de Arquivos
|
||||
|
||||
Quando arquivos são passados em múltiplos níveis, níveis mais específicos sobrescrevem os mais amplos:
|
||||
|
||||
```
|
||||
Flow input_files < Crew input_files < Task input_files
|
||||
```
|
||||
|
||||
Por exemplo, se tanto Flow quanto Task definem um arquivo chamado `"chart"`, a versão da Task é usada.
|
||||
|
||||
## Suporte por Provedor
|
||||
|
||||
Diferentes provedores suportam diferentes tipos de arquivo. O CrewAI formata automaticamente os arquivos para a API de cada provedor.
|
||||
|
||||
| Provedor | Imagem | PDF | Áudio | Vídeo | Texto |
|
||||
|:---------|:-----:|:---:|:-----:|:-----:|:----:|
|
||||
| **OpenAI** (API completions) | ✓ | | | | |
|
||||
| **OpenAI** (API responses) | ✓ | ✓ | ✓ | | |
|
||||
| **Anthropic** (claude-3.x) | ✓ | ✓ | | | |
|
||||
| **Google Gemini** (gemini-1.5, 2.0, 2.5) | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| **AWS Bedrock** (claude-3) | ✓ | ✓ | | | |
|
||||
| **Azure OpenAI** (gpt-4o) | ✓ | | ✓ | | |
|
||||
|
||||
<Note type="info" title="Gemini para Máximo Suporte de Arquivos">
|
||||
Os modelos Google Gemini suportam todos os tipos de arquivo incluindo vídeo (até 1 hora, 2GB). Use Gemini quando precisar processar conteúdo de vídeo.
|
||||
</Note>
|
||||
|
||||
<Note type="warning" title="Tipos de Arquivo Não Suportados">
|
||||
Se você passar um tipo de arquivo que o provedor não suporta (ex: vídeo para OpenAI), você receberá um `UnsupportedFileTypeError`. Escolha seu provedor baseado nos tipos de arquivo que você precisa processar.
|
||||
</Note>
|
||||
|
||||
## Como os Arquivos São Enviados
|
||||
|
||||
O CrewAI escolhe automaticamente o método ideal para enviar arquivos para cada provedor:
|
||||
|
||||
| Método | Descrição | Usado Quando |
|
||||
|:-------|:------------|:----------|
|
||||
| **Base64 Inline** | Arquivo embutido diretamente na requisição | Arquivos pequenos (< 5MB tipicamente) |
|
||||
| **API de Upload de Arquivo** | Arquivo enviado separadamente, referenciado por ID | Arquivos grandes que excedem o limite |
|
||||
| **Referência por URL** | URL direta passada para o modelo | Fonte do arquivo já é uma URL |
|
||||
|
||||
### Métodos de Transmissão por Provedor
|
||||
|
||||
| Provedor | Base64 Inline | API de Upload | Referências URL |
|
||||
|:---------|:-------------:|:---------------:|:--------------:|
|
||||
| **OpenAI** | ✓ | ✓ (> 5 MB) | ✓ |
|
||||
| **Anthropic** | ✓ | ✓ (> 5 MB) | ✓ |
|
||||
| **Google Gemini** | ✓ | ✓ (> 20 MB) | ✓ |
|
||||
| **AWS Bedrock** | ✓ | | ✓ (S3 URIs) |
|
||||
| **Azure OpenAI** | ✓ | | ✓ |
|
||||
|
||||
<Note type="info" title="Otimização Automática">
|
||||
Você não precisa gerenciar isso. O CrewAI usa automaticamente o método mais eficiente baseado no tamanho do arquivo e nas capacidades do provedor. Provedores sem APIs de upload de arquivo usam base64 inline para todos os arquivos.
|
||||
</Note>
|
||||
|
||||
## Modos de Tratamento de Arquivo
|
||||
|
||||
Controle como os arquivos são processados quando excedem os limites do provedor:
|
||||
|
||||
```python
|
||||
from crewai_files import ImageFile, PDFFile
|
||||
|
||||
image = ImageFile(source="large.png", mode="strict")
|
||||
image = ImageFile(source="large.png", mode="auto")
|
||||
image = ImageFile(source="large.png", mode="warn")
|
||||
pdf = PDFFile(source="large.pdf", mode="chunk")
|
||||
```
|
||||
|
||||
## Restrições por Provedor
|
||||
|
||||
Cada provedor tem limites específicos para tamanhos e dimensões de arquivo:
|
||||
|
||||
### OpenAI
|
||||
- **Imagens**: Máx 20 MB, até 10 imagens por requisição
|
||||
- **PDFs**: Máx 32 MB, até 100 páginas
|
||||
- **Áudio**: Máx 25 MB, até 25 minutos
|
||||
|
||||
### Anthropic
|
||||
- **Imagens**: Máx 5 MB, máx 8000x8000 pixels, até 100 imagens
|
||||
- **PDFs**: Máx 32 MB, até 100 páginas
|
||||
|
||||
### Google Gemini
|
||||
- **Imagens**: Máx 100 MB
|
||||
- **PDFs**: Máx 50 MB
|
||||
- **Áudio**: Máx 100 MB, até 9,5 horas
|
||||
- **Vídeo**: Máx 2 GB, até 1 hora
|
||||
|
||||
### AWS Bedrock
|
||||
- **Imagens**: Máx 4,5 MB, máx 8000x8000 pixels
|
||||
- **PDFs**: Máx 3,75 MB, até 100 páginas
|
||||
|
||||
## Referenciando Arquivos em Prompts
|
||||
|
||||
Use o nome da chave do arquivo nas descrições das suas tasks para referenciar arquivos:
|
||||
|
||||
```python
|
||||
task = Task(
|
||||
description="""
|
||||
Analise os materiais fornecidos:
|
||||
1. Revise o gráfico em {sales_chart}
|
||||
2. Faça referência cruzada com dados em {quarterly_report}
|
||||
3. Resuma as principais descobertas
|
||||
""",
|
||||
expected_output="Resumo da análise com insights principais",
|
||||
input_files={
|
||||
"sales_chart": ImageFile(source="chart.png"),
|
||||
"quarterly_report": PDFFile(source="report.pdf"),
|
||||
}
|
||||
)
|
||||
```
|
||||
1061
docs/edge/pt-BR/concepts/flows.mdx
Normal file
1061
docs/edge/pt-BR/concepts/flows.mdx
Normal file
File diff suppressed because it is too large
Load Diff
1060
docs/edge/pt-BR/concepts/knowledge.mdx
Normal file
1060
docs/edge/pt-BR/concepts/knowledge.mdx
Normal file
File diff suppressed because it is too large
Load Diff
1086
docs/edge/pt-BR/concepts/llms.mdx
Normal file
1086
docs/edge/pt-BR/concepts/llms.mdx
Normal file
File diff suppressed because it is too large
Load Diff
878
docs/edge/pt-BR/concepts/memory.mdx
Normal file
878
docs/edge/pt-BR/concepts/memory.mdx
Normal file
@@ -0,0 +1,878 @@
|
||||
---
|
||||
title: Memória
|
||||
description: Aproveitando o sistema de memória unificado no CrewAI para aprimorar as capacidades dos agentes.
|
||||
icon: database
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O CrewAI oferece um **sistema de memória unificado** -- uma única classe `Memory` que substitui memórias de curto prazo, longo prazo, entidades e externa por uma API inteligente. A memória usa um LLM para analisar o conteúdo ao salvar (inferindo escopo, categorias e importância) e suporta recall com profundidade adaptativa e pontuação composta que combina similaridade semântica, recência e importância.
|
||||
|
||||
Você pode usar a memória de quatro formas: **standalone** (scripts, notebooks), **com Crews**, **com Agentes** ou **dentro de Flows**.
|
||||
|
||||
## Início Rápido
|
||||
|
||||
```python
|
||||
from crewai import Memory
|
||||
|
||||
memory = Memory()
|
||||
|
||||
# Armazenar -- o LLM infere escopo, categorias e importância
|
||||
memory.remember("Decidimos usar PostgreSQL para o banco de dados de usuários.")
|
||||
|
||||
# Recuperar -- resultados ranqueados por pontuação composta (semântica + recência + importância)
|
||||
matches = memory.recall("Qual banco de dados escolhemos?")
|
||||
for m in matches:
|
||||
print(f"[{m.score:.2f}] {m.record.content}")
|
||||
|
||||
# Ajustar pontuação para um projeto dinâmico
|
||||
memory = Memory(recency_weight=0.5, recency_half_life_days=7)
|
||||
|
||||
# Esquecer
|
||||
memory.forget(scope="/project/old")
|
||||
|
||||
# Explorar a árvore de escopos auto-organizada
|
||||
print(memory.tree())
|
||||
print(memory.info("/"))
|
||||
```
|
||||
|
||||
## Quatro Formas de Usar Memória
|
||||
|
||||
### Standalone
|
||||
|
||||
Use memória em scripts, notebooks, ferramentas CLI ou como base de conhecimento independente -- sem agentes ou crews necessários.
|
||||
|
||||
```python
|
||||
from crewai import Memory
|
||||
|
||||
memory = Memory()
|
||||
|
||||
# Construir conhecimento
|
||||
memory.remember("O limite da API é 1000 requisições por minuto.")
|
||||
memory.remember("Nosso ambiente de staging usa a porta 8080.")
|
||||
memory.remember("A equipe concordou em usar feature flags para todos os novos lançamentos.")
|
||||
|
||||
# Depois, recupere o que precisar
|
||||
matches = memory.recall("Quais são nossos limites de API?", limit=5)
|
||||
for m in matches:
|
||||
print(f"[{m.score:.2f}] {m.record.content}")
|
||||
|
||||
# Extrair fatos atômicos de um texto mais longo
|
||||
raw = """Notas da reunião: Decidimos migrar do MySQL para PostgreSQL
|
||||
no próximo trimestre. O orçamento é de $50k. Sarah liderará a migração."""
|
||||
|
||||
facts = memory.extract_memories(raw)
|
||||
# ["Migração de MySQL para PostgreSQL planejada para o próximo trimestre",
|
||||
# "Orçamento da migração de banco de dados é $50k",
|
||||
# "Sarah liderará a migração do banco de dados"]
|
||||
|
||||
for fact in facts:
|
||||
memory.remember(fact)
|
||||
```
|
||||
|
||||
### Com Crews
|
||||
|
||||
Passe `memory=True` para configurações padrão, ou passe uma instância `Memory` configurada para comportamento customizado.
|
||||
|
||||
```python
|
||||
from crewai import Crew, Agent, Task, Process, Memory
|
||||
|
||||
# Opção 1: Memória padrão
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, writing_task],
|
||||
process=Process.sequential,
|
||||
memory=True,
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
# Opção 2: Memória customizada com pontuação ajustada
|
||||
memory = Memory(
|
||||
recency_weight=0.4,
|
||||
semantic_weight=0.4,
|
||||
importance_weight=0.2,
|
||||
recency_half_life_days=14,
|
||||
)
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, writing_task],
|
||||
memory=memory,
|
||||
)
|
||||
```
|
||||
|
||||
Quando `memory=True`, a crew cria um `Memory()` padrão e repassa a configuração de `embedder` da crew automaticamente. Todos os agentes compartilham a memória da crew, a menos que um agente tenha sua própria.
|
||||
|
||||
Após cada tarefa, a crew extrai automaticamente fatos discretos da saída da tarefa e os armazena. Antes de cada tarefa, o agente recupera contexto relevante da memória e o injeta no prompt da tarefa.
|
||||
|
||||
### Com Agentes
|
||||
|
||||
Agentes podem usar a memória compartilhada da crew (padrão) ou receber uma visão com escopo para contexto privado.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Memory
|
||||
|
||||
memory = Memory()
|
||||
|
||||
# Pesquisador recebe um escopo privado -- só vê /agent/researcher
|
||||
researcher = Agent(
|
||||
role="Researcher",
|
||||
goal="Encontrar e analisar informações",
|
||||
backstory="Pesquisador experiente com atenção aos detalhes",
|
||||
memory=memory.scope("/agent/researcher"),
|
||||
)
|
||||
|
||||
# Escritor usa memória compartilhada da crew (sem memória própria)
|
||||
writer = Agent(
|
||||
role="Writer",
|
||||
goal="Produzir conteúdo claro e bem estruturado",
|
||||
backstory="Escritor técnico experiente",
|
||||
# memory não definido -- usa crew._memory quando a crew tem memória habilitada
|
||||
)
|
||||
```
|
||||
|
||||
Esse padrão dá ao pesquisador descobertas privadas enquanto o escritor lê da memória compartilhada da crew.
|
||||
|
||||
### Com Flows
|
||||
|
||||
Todo Flow possui memória integrada. Use `self.remember()`, `self.recall()` e `self.extract_memories()` dentro de qualquer método do flow.
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
|
||||
class ResearchFlow(Flow):
|
||||
@start()
|
||||
def gather_data(self):
|
||||
findings = "PostgreSQL suporta 10k conexões simultâneas. MySQL limita a 5k."
|
||||
self.remember(findings, scope="/research/databases")
|
||||
return findings
|
||||
|
||||
@listen(gather_data)
|
||||
def write_report(self, findings):
|
||||
# Recuperar pesquisas anteriores para fornecer contexto
|
||||
past = self.recall("benchmarks de performance de banco de dados")
|
||||
context = "\n".join(f"- {m.record.content}" for m in past)
|
||||
return f"Relatório:\nNovas descobertas: {findings}\nContexto anterior:\n{context}"
|
||||
```
|
||||
|
||||
Veja a [documentação de Flows](/concepts/flows) para mais informações sobre memória em Flows.
|
||||
|
||||
|
||||
## Escopos Hierárquicos
|
||||
|
||||
### O Que São Escopos
|
||||
|
||||
As memórias são organizadas em uma árvore hierárquica de escopos, similar a um sistema de arquivos. Cada escopo é um caminho como `/`, `/project/alpha` ou `/agent/researcher/findings`.
|
||||
|
||||
```
|
||||
/
|
||||
/company
|
||||
/company/engineering
|
||||
/company/product
|
||||
/project
|
||||
/project/alpha
|
||||
/project/beta
|
||||
/agent
|
||||
/agent/researcher
|
||||
/agent/writer
|
||||
```
|
||||
|
||||
Escopos fornecem **memória dependente de contexto** -- quando você faz recall dentro de um escopo, busca apenas naquela ramificação da árvore, melhorando tanto a precisão quanto o desempenho.
|
||||
|
||||
### Como a Inferência de Escopo Funciona
|
||||
|
||||
Quando você chama `remember()` sem especificar um escopo, o LLM analisa o conteúdo e a árvore de escopos existente, e sugere o melhor posicionamento. Se nenhum escopo existente é adequado, ele cria um novo. Com o tempo, a árvore de escopos cresce organicamente a partir do conteúdo -- você não precisa projetar um esquema antecipadamente.
|
||||
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# LLM infere escopo a partir do conteúdo
|
||||
memory.remember("Escolhemos PostgreSQL para o banco de dados de usuários.")
|
||||
# -> pode ser colocado em /project/decisions ou /engineering/database
|
||||
|
||||
# Você também pode especificar o escopo explicitamente
|
||||
memory.remember("Velocidade do sprint é 42 pontos", scope="/team/metrics")
|
||||
```
|
||||
|
||||
### Visualizando a Árvore de Escopos
|
||||
|
||||
```python
|
||||
print(memory.tree())
|
||||
# / (15 records)
|
||||
# /project (8 records)
|
||||
# /project/alpha (5 records)
|
||||
# /project/beta (3 records)
|
||||
# /agent (7 records)
|
||||
# /agent/researcher (4 records)
|
||||
# /agent/writer (3 records)
|
||||
|
||||
print(memory.info("/project/alpha"))
|
||||
# ScopeInfo(path='/project/alpha', record_count=5,
|
||||
# categories=['architecture', 'database'],
|
||||
# oldest_record=datetime(...), newest_record=datetime(...),
|
||||
# child_scopes=[])
|
||||
```
|
||||
|
||||
### MemoryScope: Visões de Subárvore
|
||||
|
||||
Um `MemoryScope` restringe todas as operações a uma ramificação da árvore. O agente ou código que o utiliza só pode ver e escrever dentro daquela subárvore.
|
||||
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# Criar um escopo para um agente específico
|
||||
agent_memory = memory.scope("/agent/researcher")
|
||||
|
||||
# Tudo é relativo a /agent/researcher
|
||||
agent_memory.remember("Encontrados três papers relevantes sobre memória de LLM.")
|
||||
# -> armazenado em /agent/researcher
|
||||
|
||||
agent_memory.recall("papers relevantes")
|
||||
# -> busca apenas em /agent/researcher
|
||||
|
||||
# Restringir ainda mais com subscope
|
||||
project_memory = agent_memory.subscope("project-alpha")
|
||||
# -> /agent/researcher/project-alpha
|
||||
```
|
||||
|
||||
### Boas Práticas para Design de Escopos
|
||||
|
||||
- **Comece plano, deixe o LLM organizar.** Não projete demais sua hierarquia de escopos antecipadamente. Comece com `memory.remember(content)` e deixe a inferência de escopo do LLM criar estrutura conforme o conteúdo se acumula.
|
||||
|
||||
- **Use padrões `/{tipo_entidade}/{identificador}`.** Hierarquias naturais emergem de padrões como `/project/alpha`, `/agent/researcher`, `/company/engineering`, `/customer/acme-corp`.
|
||||
|
||||
- **Escopo por preocupação, não por tipo de dado.** Use `/project/alpha/decisions` em vez de `/decisions/project/alpha`. Isso mantém conteúdo relacionado junto.
|
||||
|
||||
- **Mantenha profundidade rasa (2-3 níveis).** Escopos profundamente aninhados ficam muito esparsos. `/project/alpha/architecture` é bom; `/project/alpha/architecture/decisions/databases/postgresql` é demais.
|
||||
|
||||
- **Use escopos explícitos quando souber, deixe o LLM inferir quando não souber.** Se está armazenando uma decisão de projeto conhecida, passe `scope="/project/alpha/decisions"`. Se está armazenando saída livre de um agente, omita o escopo e deixe o LLM decidir.
|
||||
|
||||
### Exemplos de Casos de Uso
|
||||
|
||||
**Equipe multi-projeto:**
|
||||
```python
|
||||
memory = Memory()
|
||||
# Cada projeto recebe sua própria ramificação
|
||||
memory.remember("Usando arquitetura de microsserviços", scope="/project/alpha/architecture")
|
||||
memory.remember("API GraphQL para apps cliente", scope="/project/beta/api")
|
||||
|
||||
# Recall em todos os projetos
|
||||
memory.recall("decisões de design de API")
|
||||
|
||||
# Ou dentro de um projeto específico
|
||||
memory.recall("design de API", scope="/project/beta")
|
||||
```
|
||||
|
||||
**Contexto privado por agente com conhecimento compartilhado:**
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# Pesquisador tem descobertas privadas
|
||||
researcher_memory = memory.scope("/agent/researcher")
|
||||
|
||||
# Escritor pode ler de seu próprio escopo e do conhecimento compartilhado da empresa
|
||||
writer_view = memory.slice(
|
||||
scopes=["/agent/writer", "/company/knowledge"],
|
||||
read_only=True,
|
||||
)
|
||||
```
|
||||
|
||||
**Suporte ao cliente (contexto por cliente):**
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# Cada cliente recebe contexto isolado
|
||||
memory.remember("Prefere comunicação por email", scope="/customer/acme-corp")
|
||||
memory.remember("Plano enterprise, 50 licenças", scope="/customer/acme-corp")
|
||||
|
||||
# Docs de produto compartilhados são acessíveis a todos os agentes
|
||||
memory.remember("Limite de taxa é 1000 req/min no plano enterprise", scope="/product/docs")
|
||||
```
|
||||
|
||||
|
||||
## Fatias de Memória (Memory Slices)
|
||||
|
||||
### O Que São Fatias
|
||||
|
||||
Um `MemorySlice` é uma visão sobre múltiplos escopos, possivelmente disjuntos. Diferente de um escopo (que restringe a uma subárvore), uma fatia permite recall de várias ramificações simultaneamente.
|
||||
|
||||
### Quando Usar Fatias vs Escopos
|
||||
|
||||
- **Escopo**: Use quando um agente ou bloco de código deve ser restrito a uma única subárvore. Exemplo: um agente que só vê `/agent/researcher`.
|
||||
- **Fatia**: Use quando precisar combinar contexto de múltiplas ramificações. Exemplo: um agente que lê de seu próprio escopo mais conhecimento compartilhado da empresa.
|
||||
|
||||
### Fatias Somente Leitura
|
||||
|
||||
O padrão mais comum: dar a um agente acesso de leitura a múltiplas ramificações sem permitir que ele escreva em áreas compartilhadas.
|
||||
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# Agente pode fazer recall de seu próprio escopo E do conhecimento da empresa,
|
||||
# mas não pode escrever no conhecimento da empresa
|
||||
agent_view = memory.slice(
|
||||
scopes=["/agent/researcher", "/company/knowledge"],
|
||||
read_only=True,
|
||||
)
|
||||
|
||||
matches = agent_view.recall("políticas de segurança da empresa", limit=5)
|
||||
# Busca em /agent/researcher e /company/knowledge, mescla e ranqueia resultados
|
||||
|
||||
agent_view.remember("nova descoberta") # Levanta PermissionError (somente leitura)
|
||||
```
|
||||
|
||||
### Fatias de Leitura e Escrita
|
||||
|
||||
Quando somente leitura está desabilitado, você pode escrever em qualquer um dos escopos incluídos, mas deve especificar qual escopo explicitamente.
|
||||
|
||||
```python
|
||||
view = memory.slice(scopes=["/team/alpha", "/team/beta"], read_only=False)
|
||||
|
||||
# Deve especificar escopo ao escrever
|
||||
view.remember("Decisão entre equipes", scope="/team/alpha", categories=["decisions"])
|
||||
```
|
||||
|
||||
|
||||
## Pontuação Composta
|
||||
|
||||
Os resultados do recall são ranqueados por uma combinação ponderada de três sinais:
|
||||
|
||||
```
|
||||
composite = semantic_weight * similarity + recency_weight * decay + importance_weight * importance
|
||||
```
|
||||
|
||||
Onde:
|
||||
- **similarity** = `1 / (1 + distance)` do índice vetorial (0 a 1)
|
||||
- **decay** = `0.5^(age_days / half_life_days)` -- decaimento exponencial (1.0 para hoje, 0.5 na meia-vida)
|
||||
- **importance** = pontuação de importância do registro (0 a 1), definida no momento da codificação
|
||||
|
||||
Configure diretamente no construtor do `Memory`:
|
||||
|
||||
```python
|
||||
# Retrospectiva de sprint: favorecer memórias recentes, meia-vida curta
|
||||
memory = Memory(
|
||||
recency_weight=0.5,
|
||||
semantic_weight=0.3,
|
||||
importance_weight=0.2,
|
||||
recency_half_life_days=7,
|
||||
)
|
||||
|
||||
# Base de conhecimento de arquitetura: favorecer memórias importantes, meia-vida longa
|
||||
memory = Memory(
|
||||
recency_weight=0.1,
|
||||
semantic_weight=0.5,
|
||||
importance_weight=0.4,
|
||||
recency_half_life_days=180,
|
||||
)
|
||||
```
|
||||
|
||||
Cada `MemoryMatch` inclui uma lista `match_reasons` para que você possa ver por que um resultado ficou na posição que ficou (ex.: `["semantic", "recency", "importance"]`).
|
||||
|
||||
|
||||
## Camada de Análise LLM
|
||||
|
||||
A memória usa o LLM de três formas:
|
||||
|
||||
1. **Ao salvar** -- Quando você omite escopo, categorias ou importância, o LLM analisa o conteúdo e sugere escopo, categorias, importância e metadados (entidades, datas, tópicos).
|
||||
2. **Ao fazer recall** -- Para recall profundo/automático, o LLM analisa a consulta (palavras-chave, dicas temporais, escopos sugeridos, complexidade) para guiar a recuperação.
|
||||
3. **Extrair memórias** -- `extract_memories(content)` quebra texto bruto (ex.: saída de tarefa) em afirmações de memória discretas. Os agentes usam isso antes de chamar `remember()` em cada afirmação para que fatos atômicos sejam armazenados em vez de um bloco grande.
|
||||
|
||||
Toda análise degrada graciosamente em caso de falha do LLM -- veja [Comportamento em Caso de Falha](#comportamento-em-caso-de-falha).
|
||||
|
||||
|
||||
## Consolidação de Memória
|
||||
|
||||
Ao salvar novo conteúdo, o pipeline de codificação verifica automaticamente registros similares existentes no armazenamento. Se a similaridade estiver acima de `consolidation_threshold` (padrão 0.85), o LLM decide o que fazer:
|
||||
|
||||
- **keep** -- O registro existente ainda é preciso e não é redundante.
|
||||
- **update** -- O registro existente deve ser atualizado com novas informações (o LLM fornece o conteúdo mesclado).
|
||||
- **delete** -- O registro existente está desatualizado, substituído ou contradito.
|
||||
- **insert_new** -- Se o novo conteúdo também deve ser inserido como um registro separado.
|
||||
|
||||
Isso evita o acúmulo de duplicatas. Por exemplo, se você salvar "CrewAI garante operação confiável" três vezes, a consolidação reconhece as duplicatas e mantém apenas um registro.
|
||||
|
||||
### Dedup Intra-batch
|
||||
|
||||
Ao usar `remember_many()`, os itens dentro do mesmo batch são comparados entre si antes de atingir o armazenamento. Se dois itens tiverem similaridade de cosseno >= `batch_dedup_threshold` (padrão 0.98), o posterior é silenciosamente descartado. Isso captura duplicatas exatas ou quase exatas dentro de um único batch sem chamadas ao LLM (pura matemática vetorial).
|
||||
|
||||
```python
|
||||
# Apenas 2 registros são armazenados (o terceiro é quase duplicata do primeiro)
|
||||
memory.remember_many([
|
||||
"CrewAI supports complex workflows.",
|
||||
"Python is a great language.",
|
||||
"CrewAI supports complex workflows.", # descartado pelo dedup intra-batch
|
||||
])
|
||||
```
|
||||
|
||||
|
||||
## Saves Não-Bloqueantes
|
||||
|
||||
`remember_many()` é **não-bloqueante** -- ele envia o pipeline de codificação para uma thread em background e retorna imediatamente. Isso significa que o agente pode continuar para a próxima tarefa enquanto as memórias estão sendo salvas.
|
||||
|
||||
```python
|
||||
# Retorna imediatamente -- save acontece em background
|
||||
memory.remember_many(["Fato A.", "Fato B.", "Fato C."])
|
||||
|
||||
# recall() espera automaticamente saves pendentes antes de buscar
|
||||
matches = memory.recall("fatos") # vê todos os 3 registros
|
||||
```
|
||||
|
||||
### Barreira de Leitura
|
||||
|
||||
Cada chamada `recall()` executa automaticamente `drain_writes()` antes de buscar, garantindo que a consulta sempre veja os registros mais recentes persistidos. Isso é transparente -- você nunca precisa pensar nisso.
|
||||
|
||||
### Encerramento da Crew
|
||||
|
||||
Quando uma crew termina, `kickoff()` drena todos os saves de memória pendentes em seu bloco `finally`, então nenhum save é perdido mesmo que a crew complete enquanto saves em background estão em andamento.
|
||||
|
||||
### Uso Standalone
|
||||
|
||||
Para scripts ou notebooks onde não há ciclo de vida de crew, chame `drain_writes()` ou `close()` explicitamente:
|
||||
|
||||
```python
|
||||
memory = Memory()
|
||||
memory.remember_many(["Fato A.", "Fato B."])
|
||||
|
||||
# Opção 1: Esperar saves pendentes
|
||||
memory.drain_writes()
|
||||
|
||||
# Opção 2: Drenar e encerrar o pool de background
|
||||
memory.close()
|
||||
```
|
||||
|
||||
|
||||
## Origem e Privacidade
|
||||
|
||||
Cada registro de memória pode carregar uma tag `source` para rastreamento de procedência e uma flag `private` para controle de acesso.
|
||||
|
||||
### Rastreamento de Origem
|
||||
|
||||
O parâmetro `source` identifica de onde uma memória veio:
|
||||
|
||||
```python
|
||||
# Marcar memórias com sua origem
|
||||
memory.remember("Usuário prefere modo escuro", source="user:alice")
|
||||
memory.remember("Configuração do sistema atualizada", source="admin")
|
||||
memory.remember("Agente encontrou um bug", source="agent:debugger")
|
||||
|
||||
# Recuperar apenas memórias de uma origem específica
|
||||
matches = memory.recall("preferências do usuário", source="user:alice")
|
||||
```
|
||||
|
||||
### Memórias Privadas
|
||||
|
||||
Memórias privadas só são visíveis no recall quando o `source` corresponde:
|
||||
|
||||
```python
|
||||
# Armazenar uma memória privada
|
||||
memory.remember("A chave de API da Alice é sk-...", source="user:alice", private=True)
|
||||
|
||||
# Este recall vê a memória privada (source corresponde)
|
||||
matches = memory.recall("chave de API", source="user:alice")
|
||||
|
||||
# Este recall NÃO a vê (source diferente)
|
||||
matches = memory.recall("chave de API", source="user:bob")
|
||||
|
||||
# Acesso admin: ver todos os registros privados independente do source
|
||||
matches = memory.recall("chave de API", include_private=True)
|
||||
```
|
||||
|
||||
Isso é particularmente útil em implantações multi-usuário ou corporativas onde memórias de diferentes usuários devem ser isoladas.
|
||||
|
||||
|
||||
## RecallFlow (Recall Profundo)
|
||||
|
||||
`recall()` suporta duas profundidades:
|
||||
|
||||
- **`depth="shallow"`** -- Busca vetorial direta com pontuação composta. Rápido (~200ms), sem chamadas ao LLM.
|
||||
- **`depth="deep"` (padrão)** -- Executa um RecallFlow em múltiplas etapas: análise da consulta, seleção de escopo, busca vetorial paralela, roteamento baseado em confiança e exploração recursiva opcional quando a confiança é baixa.
|
||||
|
||||
**Pulo inteligente do LLM**: Consultas com menos de `query_analysis_threshold` (padrão 200 caracteres) pulam a análise de consulta do LLM inteiramente, mesmo no modo deep. Consultas curtas como "Qual banco de dados usamos?" já são boas frases de busca -- a análise do LLM agrega pouco valor. Isso economiza ~1-3s por recall para consultas curtas típicas. Apenas consultas mais longas (ex.: descrições completas de tarefas) passam pela destilação do LLM em sub-consultas direcionadas.
|
||||
|
||||
```python
|
||||
# Shallow: busca vetorial pura, sem LLM
|
||||
matches = memory.recall("O que decidimos?", limit=10, depth="shallow")
|
||||
|
||||
# Deep (padrão): recuperação inteligente com análise LLM para consultas longas
|
||||
matches = memory.recall(
|
||||
"Resuma todas as decisões de arquitetura deste trimestre",
|
||||
limit=10,
|
||||
depth="deep",
|
||||
)
|
||||
```
|
||||
|
||||
Os limiares de confiança que controlam o roteador do RecallFlow são configuráveis:
|
||||
|
||||
```python
|
||||
memory = Memory(
|
||||
confidence_threshold_high=0.9, # Só sintetizar quando muito confiante
|
||||
confidence_threshold_low=0.4, # Explorar mais profundamente de forma mais agressiva
|
||||
exploration_budget=2, # Permitir até 2 rodadas de exploração
|
||||
query_analysis_threshold=200, # Pular LLM para consultas menores que isso
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
## Configuração de Embedder
|
||||
|
||||
A memória precisa de um modelo de embedding para converter texto em vetores para busca semântica. Você pode configurar de três formas.
|
||||
|
||||
### Passando Diretamente para o Memory
|
||||
|
||||
```python
|
||||
from crewai import Memory
|
||||
|
||||
# Como um dict de configuração
|
||||
memory = Memory(embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}})
|
||||
|
||||
# Como um callable pré-construído
|
||||
from crewai.rag.embeddings.factory import build_embedder
|
||||
embedder = build_embedder({"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}})
|
||||
memory = Memory(embedder=embedder)
|
||||
```
|
||||
|
||||
### Via Configuração de Embedder da Crew
|
||||
|
||||
Quando usar `memory=True`, a configuração de `embedder` da crew é repassada:
|
||||
|
||||
```python
|
||||
from crewai import Crew
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
memory=True,
|
||||
embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}},
|
||||
)
|
||||
```
|
||||
|
||||
### Exemplos por Provedor
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="OpenAI (padrão)">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model_name": "text-embedding-3-small",
|
||||
# "api_key": "sk-...", # ou defina OPENAI_API_KEY
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ollama (local, privado)">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "ollama",
|
||||
"config": {
|
||||
"model_name": "mxbai-embed-large",
|
||||
"url": "http://localhost:11434/api/embeddings",
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Azure OpenAI">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "azure",
|
||||
"config": {
|
||||
"deployment_id": "your-embedding-deployment",
|
||||
"api_key": "your-azure-api-key",
|
||||
"api_base": "https://your-resource.openai.azure.com",
|
||||
"api_version": "2024-02-01",
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Google AI">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "google-generativeai",
|
||||
"config": {
|
||||
"model_name": "gemini-embedding-001",
|
||||
# "api_key": "...", # ou defina GOOGLE_API_KEY
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Google Vertex AI">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "google-vertex",
|
||||
"config": {
|
||||
"model_name": "gemini-embedding-001",
|
||||
"project_id": "your-gcp-project-id",
|
||||
"location": "us-central1",
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Cohere">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "cohere",
|
||||
"config": {
|
||||
"model_name": "embed-english-v3.0",
|
||||
# "api_key": "...", # ou defina COHERE_API_KEY
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="VoyageAI">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "voyageai",
|
||||
"config": {
|
||||
"model": "voyage-3",
|
||||
# "api_key": "...", # ou defina VOYAGE_API_KEY
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="AWS Bedrock">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "amazon-bedrock",
|
||||
"config": {
|
||||
"model_name": "amazon.titan-embed-text-v1",
|
||||
# Usa credenciais AWS padrão (sessão boto3)
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Hugging Face">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "huggingface",
|
||||
"config": {
|
||||
"model_name": "sentence-transformers/all-MiniLM-L6-v2",
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Jina">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "jina",
|
||||
"config": {
|
||||
"model_name": "jina-embeddings-v2-base-en",
|
||||
# "api_key": "...", # ou defina JINA_API_KEY
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="IBM WatsonX">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "watsonx",
|
||||
"config": {
|
||||
"model_id": "ibm/slate-30m-english-rtrvr",
|
||||
"api_key": "your-watsonx-api-key",
|
||||
"project_id": "your-project-id",
|
||||
"url": "https://us-south.ml.cloud.ibm.com",
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Embedder Customizado">
|
||||
```python
|
||||
# Passe qualquer callable que receba uma lista de strings e retorne uma lista de vetores
|
||||
def my_embedder(texts: list[str]) -> list[list[float]]:
|
||||
# Sua lógica de embedding aqui
|
||||
return [[0.1, 0.2, ...] for _ in texts]
|
||||
|
||||
memory = Memory(embedder=my_embedder)
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Referência de Provedores
|
||||
|
||||
| Provedor | Chave | Modelo Típico | Notas |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| OpenAI | `openai` | `text-embedding-3-small` | Padrão. Defina `OPENAI_API_KEY`. |
|
||||
| Ollama | `ollama` | `mxbai-embed-large` | Local, sem API key. |
|
||||
| Azure OpenAI | `azure` | `text-embedding-ada-002` | Requer `deployment_id`. |
|
||||
| Google AI | `google-generativeai` | `gemini-embedding-001` | Defina `GOOGLE_API_KEY`. |
|
||||
| Google Vertex | `google-vertex` | `gemini-embedding-001` | Requer `project_id`. |
|
||||
| Cohere | `cohere` | `embed-english-v3.0` | Forte suporte multilíngue. |
|
||||
| VoyageAI | `voyageai` | `voyage-3` | Otimizado para retrieval. |
|
||||
| AWS Bedrock | `amazon-bedrock` | `amazon.titan-embed-text-v1` | Usa credenciais boto3. |
|
||||
| Hugging Face | `huggingface` | `all-MiniLM-L6-v2` | Sentence-transformers local. |
|
||||
| Jina | `jina` | `jina-embeddings-v2-base-en` | Defina `JINA_API_KEY`. |
|
||||
| IBM WatsonX | `watsonx` | `ibm/slate-30m-english-rtrvr` | Requer `project_id`. |
|
||||
| Sentence Transformer | `sentence-transformer` | `all-MiniLM-L6-v2` | Local, sem API key. |
|
||||
| Custom | `custom` | -- | Requer `embedding_callable`. |
|
||||
|
||||
|
||||
## Configuração de LLM
|
||||
|
||||
A memória usa um LLM para análise de save (inferência de escopo, categorias e importância), decisões de consolidação e análise de consulta no recall profundo. Você pode configurar qual modelo usar.
|
||||
|
||||
```python
|
||||
from crewai import Memory, LLM
|
||||
|
||||
# Padrão: gpt-4o-mini
|
||||
memory = Memory()
|
||||
|
||||
# Usar um modelo OpenAI diferente
|
||||
memory = Memory(llm="gpt-4o")
|
||||
|
||||
# Usar Anthropic
|
||||
memory = Memory(llm="anthropic/claude-3-haiku-20240307")
|
||||
|
||||
# Usar Ollama para análise totalmente local/privada
|
||||
memory = Memory(llm="ollama/llama3.2")
|
||||
|
||||
# Usar Google Gemini
|
||||
memory = Memory(llm="gemini/gemini-2.0-flash")
|
||||
|
||||
# Passar uma instância LLM pré-configurada com configurações customizadas
|
||||
llm = LLM(model="gpt-4o", temperature=0)
|
||||
memory = Memory(llm=llm)
|
||||
```
|
||||
|
||||
O LLM é inicializado **lazily** -- ele só é criado quando necessário pela primeira vez. Isso significa que `Memory()` nunca falha no momento da construção, mesmo que chaves de API não estejam definidas. Erros só aparecem quando o LLM é realmente chamado (ex.: ao salvar sem escopo/categorias explícitos, ou durante recall profundo).
|
||||
|
||||
Para operação totalmente offline/privada, use um modelo local tanto para o LLM quanto para o embedder:
|
||||
|
||||
```python
|
||||
memory = Memory(
|
||||
llm="ollama/llama3.2",
|
||||
embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}},
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
## Backend de Armazenamento
|
||||
|
||||
- **Padrão**: LanceDB, armazenado em `./.crewai/memory` (ou `$CREWAI_STORAGE_DIR/memory` se a variável de ambiente estiver definida, ou o caminho que você passar como `storage="path/to/dir"`).
|
||||
- **Backend customizado**: Implemente o protocolo `StorageBackend` (veja `crewai.memory.storage.backend`) e passe uma instância para `Memory(storage=your_backend)`.
|
||||
|
||||
|
||||
## Descoberta
|
||||
|
||||
Inspecione a hierarquia de escopos, categorias e registros:
|
||||
|
||||
```python
|
||||
memory.tree() # Árvore formatada de escopos e contagem de registros
|
||||
memory.tree("/project", max_depth=2) # Visão de subárvore
|
||||
memory.info("/project") # ScopeInfo: record_count, categories, oldest/newest
|
||||
memory.list_scopes("/") # Escopos filhos imediatos
|
||||
memory.list_categories() # Nomes e contagens de categorias
|
||||
memory.list_records(scope="/project/alpha", limit=20) # Registros em um escopo, mais recentes primeiro
|
||||
```
|
||||
|
||||
|
||||
## Comportamento em Caso de Falha
|
||||
|
||||
Se o LLM falhar durante a análise (erro de rede, limite de taxa, resposta inválida), a memória degrada graciosamente:
|
||||
|
||||
- **Análise de save** -- Um aviso é registrado e a memória ainda é armazenada com escopo padrão `/`, categorias vazias e importância `0.5`.
|
||||
- **Extrair memórias** -- O conteúdo completo é armazenado como uma única memória para que nada seja descartado.
|
||||
- **Análise de consulta** -- O recall usa fallback para seleção simples de escopo e busca vetorial, então você ainda obtém resultados.
|
||||
|
||||
Nenhuma exceção é levantada para essas falhas de análise; apenas falhas de armazenamento ou do embedder irão levantar.
|
||||
|
||||
|
||||
## Nota sobre Privacidade
|
||||
|
||||
O conteúdo da memória é enviado ao LLM configurado para análise (escopo/categorias/importância no save, análise de consulta e recall profundo opcional). Para dados sensíveis, use um LLM local (ex.: Ollama) ou garanta que seu provedor atenda aos requisitos de conformidade.
|
||||
|
||||
|
||||
## Eventos de Memória
|
||||
|
||||
Todas as operações de memória emitem eventos com `source_type="unified_memory"`. Você pode escutar para timing, erros e conteúdo.
|
||||
|
||||
| Evento | Descrição | Propriedades Principais |
|
||||
| :---- | :---------- | :------------- |
|
||||
| **MemoryQueryStartedEvent** | Consulta inicia | `query`, `limit` |
|
||||
| **MemoryQueryCompletedEvent** | Consulta bem-sucedida | `query`, `results`, `query_time_ms` |
|
||||
| **MemoryQueryFailedEvent** | Consulta falha | `query`, `error` |
|
||||
| **MemorySaveStartedEvent** | Save inicia | `value`, `metadata` |
|
||||
| **MemorySaveCompletedEvent** | Save bem-sucedido | `value`, `save_time_ms` |
|
||||
| **MemorySaveFailedEvent** | Save falha | `value`, `error` |
|
||||
| **MemoryRetrievalStartedEvent** | Retrieval do agente inicia | `task_id` |
|
||||
| **MemoryRetrievalCompletedEvent** | Retrieval do agente completo | `task_id`, `memory_content`, `retrieval_time_ms` |
|
||||
|
||||
Exemplo: monitorar tempo de consulta:
|
||||
|
||||
```python
|
||||
from crewai.events import BaseEventListener, MemoryQueryCompletedEvent
|
||||
|
||||
class MemoryMonitor(BaseEventListener):
|
||||
def setup_listeners(self, crewai_event_bus):
|
||||
@crewai_event_bus.on(MemoryQueryCompletedEvent)
|
||||
def on_done(source, event):
|
||||
if getattr(event, "source_type", None) == "unified_memory":
|
||||
print(f"Query '{event.query}' completou em {event.query_time_ms:.0f}ms")
|
||||
```
|
||||
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
**Memória não persiste?**
|
||||
- Garanta que o caminho de armazenamento seja gravável (padrão `./.crewai/memory`). Passe `storage="./your_path"` para usar outro diretório, ou defina a variável de ambiente `CREWAI_STORAGE_DIR`.
|
||||
- Ao usar uma crew, confirme que `memory=True` ou `memory=Memory(...)` está definido.
|
||||
|
||||
**Recall lento?**
|
||||
- Use `depth="shallow"` para contexto rotineiro do agente. Reserve `depth="deep"` para consultas complexas.
|
||||
- Aumente `query_analysis_threshold` para pular a análise do LLM em mais consultas.
|
||||
|
||||
**Erros de análise LLM nos logs?**
|
||||
- A memória ainda salva/recupera com padrões seguros. Verifique chaves de API, limites de taxa e disponibilidade do modelo se quiser análise LLM completa.
|
||||
|
||||
**Erros de save em background nos logs?**
|
||||
- Os saves de memória rodam em uma thread em background. Erros são emitidos como `MemorySaveFailedEvent` mas não derrubam o agente. Verifique os logs para a causa raiz (geralmente problemas de conexão com LLM ou embedder).
|
||||
|
||||
**Conflitos de escrita concorrente?**
|
||||
- As operações do LanceDB são serializadas com um lock compartilhado e reexecutadas automaticamente em caso de conflito. Isso lida com múltiplas instâncias `Memory` apontando para o mesmo banco de dados (ex.: memória do agente + memória da crew). Nenhuma ação necessária.
|
||||
|
||||
**Navegar na memória pelo terminal:**
|
||||
```bash
|
||||
crewai memory # Abre o navegador TUI
|
||||
crewai memory --storage-path ./my_memory # Apontar para um diretório específico
|
||||
```
|
||||
|
||||
**Resetar memória (ex.: para testes):**
|
||||
```python
|
||||
crew.reset_memories(command_type="memory") # Reseta memória unificada
|
||||
# Ou em uma instância Memory:
|
||||
memory.reset() # Todos os escopos
|
||||
memory.reset(scope="/project/old") # Apenas essa subárvore
|
||||
```
|
||||
|
||||
|
||||
## Referência de Configuração
|
||||
|
||||
Toda a configuração é passada como argumentos nomeados para `Memory(...)`. Cada parâmetro tem um padrão sensato.
|
||||
|
||||
| Parâmetro | Padrão | Descrição |
|
||||
| :--- | :--- | :--- |
|
||||
| `llm` | `"gpt-4o-mini"` | LLM para análise (nome do modelo ou instância `BaseLLM`). |
|
||||
| `storage` | `"lancedb"` | Backend de armazenamento (`"lancedb"`, string de caminho ou instância `StorageBackend`). |
|
||||
| `embedder` | `None` (OpenAI padrão) | Embedder (dict de config, callable ou `None` para OpenAI padrão). |
|
||||
| `recency_weight` | `0.3` | Peso da recência na pontuação composta. |
|
||||
| `semantic_weight` | `0.5` | Peso da similaridade semântica na pontuação composta. |
|
||||
| `importance_weight` | `0.2` | Peso da importância na pontuação composta. |
|
||||
| `recency_half_life_days` | `30` | Dias para a pontuação de recência cair pela metade (decaimento exponencial). |
|
||||
| `consolidation_threshold` | `0.85` | Similaridade acima da qual a consolidação é ativada no save. Defina `1.0` para desativar. |
|
||||
| `consolidation_limit` | `5` | Máx. de registros existentes para comparar durante consolidação. |
|
||||
| `default_importance` | `0.5` | Importância atribuída quando não fornecida e a análise LLM é pulada. |
|
||||
| `batch_dedup_threshold` | `0.98` | Similaridade de cosseno para descartar quase-duplicatas dentro de um batch `remember_many()`. |
|
||||
| `confidence_threshold_high` | `0.8` | Confiança de recall acima da qual resultados são retornados diretamente. |
|
||||
| `confidence_threshold_low` | `0.5` | Confiança de recall abaixo da qual exploração mais profunda é ativada. |
|
||||
| `complex_query_threshold` | `0.7` | Para consultas complexas, explorar mais profundamente abaixo desta confiança. |
|
||||
| `exploration_budget` | `1` | Número de rodadas de exploração por LLM durante recall profundo. |
|
||||
| `query_analysis_threshold` | `200` | Consultas menores que isso (em caracteres) pulam análise LLM durante recall profundo. |
|
||||
153
docs/edge/pt-BR/concepts/planning.mdx
Normal file
153
docs/edge/pt-BR/concepts/planning.mdx
Normal file
@@ -0,0 +1,153 @@
|
||||
---
|
||||
title: Planejamento
|
||||
description: Aprenda como adicionar planejamento à sua CrewAI Crew e melhorar sua performance.
|
||||
icon: ruler-combined
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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
|
||||
minha_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/edge/pt-BR/concepts/processes.mdx
Normal file
66
docs/edge/pt-BR/concepts/processes.mdx
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Processos
|
||||
description: Guia detalhado sobre o gerenciamento de fluxos de trabalho através de processos no CrewAI, com detalhes de implementação atualizados.
|
||||
icon: bars-staggered
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
## 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=meus_agentes,
|
||||
tasks=minhas_tarefas,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
# Exemplo: Criando uma crew com processo hierárquico
|
||||
# Certifique-se de fornecer um manager_llm ou manager_agent
|
||||
crew = Crew(
|
||||
agents=meus_agentes,
|
||||
tasks=minhas_tarefas,
|
||||
process=Process.hierarchical,
|
||||
manager_llm="gpt-4o"
|
||||
# ou
|
||||
# manager_agent=meu_agente_gerente
|
||||
)
|
||||
```
|
||||
**Nota:** Certifique-se de que `meus_agentes` e `minhas_tarefas` 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`).
|
||||
|
||||
## 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 e melhorias, garantindo que os usuários tenham acesso às informações mais atuais e abrangentes.
|
||||
162
docs/edge/pt-BR/concepts/production-architecture.mdx
Normal file
162
docs/edge/pt-BR/concepts/production-architecture.mdx
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
title: Arquitetura de Produção
|
||||
description: Melhores práticas para construir aplicações de IA prontas para produção com CrewAI
|
||||
icon: server
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# A Mentalidade Flow-First
|
||||
|
||||
Ao construir aplicações de IA de produção com CrewAI, **recomendamos começar com um Flow**.
|
||||
|
||||
Embora seja possível executar Crews ou Agentes individuais, envolvê-los em um Flow fornece a estrutura necessária para uma aplicação robusta e escalável.
|
||||
|
||||
## Por que Flows?
|
||||
|
||||
1. **Gerenciamento de Estado**: Flows fornecem uma maneira integrada de gerenciar o estado em diferentes etapas da sua aplicação. Isso é crucial para passar dados entre Crews, manter o contexto e lidar com entradas do usuário.
|
||||
2. **Controle**: Flows permitem definir caminhos de execução precisos, incluindo loops, condicionais e lógica de ramificação. Isso é essencial para lidar com casos extremos e garantir que sua aplicação se comporte de maneira previsível.
|
||||
3. **Observabilidade**: Flows fornecem uma estrutura clara que facilita o rastreamento da execução, a depuração de problemas e o monitoramento do desempenho. Recomendamos o uso do [CrewAI Tracing](/pt-BR/observability/tracing) para insights detalhados. Basta executar `crewai login` para habilitar recursos de observabilidade gratuitos.
|
||||
|
||||
## A Arquitetura
|
||||
|
||||
Uma aplicação CrewAI de produção típica se parece com isso:
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Start((Início)) --> Flow[Orquestrador de Flow]
|
||||
Flow --> State{Gerenciamento de Estado}
|
||||
State --> Step1[Etapa 1: Coleta de Dados]
|
||||
Step1 --> Crew1[Crew de Pesquisa]
|
||||
Crew1 --> State
|
||||
State --> Step2{Verificação de Condição}
|
||||
Step2 -- "Válido" --> Step3[Etapa 3: Execução]
|
||||
Step3 --> Crew2[Crew de Ação]
|
||||
Step2 -- "Inválido" --> End((Fim))
|
||||
Crew2 --> End
|
||||
```
|
||||
|
||||
### 1. A Classe Flow
|
||||
Sua classe `Flow` é o ponto de entrada. Ela define o esquema de estado e os métodos que executam sua lógica.
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
from pydantic import BaseModel
|
||||
|
||||
class AppState(BaseModel):
|
||||
user_input: str = ""
|
||||
research_results: str = ""
|
||||
final_report: str = ""
|
||||
|
||||
class ProductionFlow(Flow[AppState]):
|
||||
@start()
|
||||
def gather_input(self):
|
||||
# ... lógica para obter entrada ...
|
||||
pass
|
||||
|
||||
@listen(gather_input)
|
||||
def run_research_crew(self):
|
||||
# ... acionar um Crew ...
|
||||
pass
|
||||
```
|
||||
|
||||
### 2. Gerenciamento de Estado
|
||||
Use modelos Pydantic para definir seu estado. Isso garante a segurança de tipos e deixa claro quais dados estão disponíveis em cada etapa.
|
||||
|
||||
- **Mantenha o mínimo**: Armazene apenas o que você precisa persistir entre as etapas.
|
||||
- **Use dados estruturados**: Evite dicionários não estruturados quando possível.
|
||||
|
||||
### 3. Crews como Unidades de Trabalho
|
||||
Delegue tarefas complexas para Crews. Um Crew deve ser focado em um objetivo específico (por exemplo, "Pesquisar um tópico", "Escrever uma postagem no blog").
|
||||
|
||||
- **Não superengendre Crews**: Mantenha-os focados.
|
||||
- **Passe o estado explicitamente**: Passe os dados necessários do estado do Flow para as entradas do Crew.
|
||||
|
||||
```python
|
||||
@listen(gather_input)
|
||||
def run_research_crew(self):
|
||||
crew = ResearchCrew()
|
||||
result = crew.kickoff(inputs={"topic": self.state.user_input})
|
||||
self.state.research_results = result.raw
|
||||
```
|
||||
|
||||
## Primitivas de Controle
|
||||
|
||||
Aproveite as primitivas de controle do CrewAI para adicionar robustez e controle aos seus Crews.
|
||||
|
||||
### 1. Task Guardrails
|
||||
Use [Task Guardrails](/pt-BR/concepts/tasks#task-guardrails) para validar as saídas das tarefas antes que sejam aceitas. Isso garante que seus agentes produzam resultados de alta qualidade.
|
||||
|
||||
```python
|
||||
def validate_content(result: TaskOutput) -> Tuple[bool, Any]:
|
||||
if len(result.raw) < 100:
|
||||
return (False, "Content is too short. Please expand.")
|
||||
return (True, result.raw)
|
||||
|
||||
task = Task(
|
||||
...,
|
||||
guardrail=validate_content
|
||||
)
|
||||
```
|
||||
|
||||
### 2. Saídas Estruturadas
|
||||
Sempre use saídas estruturadas (`output_pydantic` ou `output_json`) ao passar dados entre tarefas ou para sua aplicação. Isso evita erros de análise e garante a segurança de tipos.
|
||||
|
||||
```python
|
||||
class ResearchResult(BaseModel):
|
||||
summary: str
|
||||
sources: List[str]
|
||||
|
||||
task = Task(
|
||||
...,
|
||||
output_pydantic=ResearchResult
|
||||
)
|
||||
```
|
||||
|
||||
### 3. LLM Hooks
|
||||
Use [LLM Hooks](/pt-BR/learn/llm-hooks) para inspecionar ou modificar mensagens antes que elas sejam enviadas para o LLM, ou para higienizar respostas.
|
||||
|
||||
```python
|
||||
@before_llm_call
|
||||
def log_request(context):
|
||||
print(f"Agent {context.agent.role} is calling the LLM...")
|
||||
```
|
||||
|
||||
## Padrões de Implantação
|
||||
|
||||
Ao implantar seu Flow, considere o seguinte:
|
||||
|
||||
### CrewAI Enterprise
|
||||
A maneira mais fácil de implantar seu Flow é usando o CrewAI Enterprise. Ele lida com a infraestrutura, autenticação e monitoramento para você.
|
||||
|
||||
Confira o [Guia de Implantação](/pt-BR/enterprise/guides/deploy-to-amp) para começar.
|
||||
|
||||
```bash
|
||||
crewai deploy create
|
||||
```
|
||||
|
||||
### Execução Assíncrona
|
||||
Para tarefas de longa duração, use `kickoff_async` para evitar bloquear sua API.
|
||||
|
||||
### Persistência
|
||||
Use o decorador `@persist` para salvar o estado do seu Flow em um banco de dados. Isso permite retomar a execução se o processo falhar ou se você precisar esperar pela entrada humana.
|
||||
|
||||
```python
|
||||
@persist
|
||||
class ProductionFlow(Flow[AppState]):
|
||||
# ...
|
||||
```
|
||||
|
||||
Por padrão, `@persist` retoma um flow quando `kickoff(inputs={"id": <uuid>})` é informado, estendendo o mesmo histórico do `flow_uuid`. Para **forkar** um flow persistido em uma nova linhagem — hidratar o estado a partir de uma execução anterior mas escrever sob um novo `state.id` — passe `restore_from_state_id`:
|
||||
|
||||
```python
|
||||
flow.kickoff(restore_from_state_id="<previous-run-state-id>")
|
||||
```
|
||||
|
||||
A nova execução recebe um novo `state.id` (auto-gerado, ou `inputs["id"]` se fixado), então suas escritas do `@persist` não estendem o histórico da origem. Combinar com `from_checkpoint` lança um `ValueError`; escolha uma única fonte de hidratação.
|
||||
|
||||
## Resumo
|
||||
|
||||
- **Comece com um Flow.**
|
||||
- **Defina um Estado claro.**
|
||||
- **Use Crews para tarefas complexas.**
|
||||
- **Implante com uma API e persistência.**
|
||||
148
docs/edge/pt-BR/concepts/reasoning.mdx
Normal file
148
docs/edge/pt-BR/concepts/reasoning.mdx
Normal file
@@ -0,0 +1,148 @@
|
||||
---
|
||||
title: Reasoning
|
||||
description: "Aprenda como habilitar e usar o reasoning do agente para aprimorar a execução de tarefas."
|
||||
icon: brain
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
analista = Agent(
|
||||
role="Analista de Dados",
|
||||
goal="Analisar dados e fornecer insights",
|
||||
backstory="Você é um analista de dados especialista.",
|
||||
reasoning=True,
|
||||
max_reasoning_attempts=3 # Opcional: Defina um limite de tentativas de reasoning
|
||||
)
|
||||
```
|
||||
|
||||
## 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
|
||||
analista = Agent(
|
||||
role="Analista de Dados",
|
||||
goal="Analisar dados e fornecer insights",
|
||||
backstory="Você é um analista de dados especialista.",
|
||||
reasoning=True,
|
||||
max_reasoning_attempts=3 # Opcional: Defina um limite de tentativas de reasoning
|
||||
)
|
||||
|
||||
# Create a task
|
||||
analysis_task = Task(
|
||||
description="Analise os dados de vendas fornecidos e identifique as principais tendências.",
|
||||
expected_output="Um relatório destacando as 3 principais tendências de vendas.",
|
||||
agent=analista
|
||||
)
|
||||
|
||||
# Create a crew and run the task
|
||||
crew = Crew(agents=[analista], 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="Analista de Dados",
|
||||
goal="Analisar dados e fornecer insights",
|
||||
reasoning=True,
|
||||
max_reasoning_attempts=3
|
||||
)
|
||||
|
||||
# Create a task
|
||||
task = Task(
|
||||
description="Analise os dados de vendas fornecidos e identifique as principais tendências.",
|
||||
expected_output="Um relatório destacando as 3 principais tendências de vendas.",
|
||||
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: Analise os dados de vendas fornecidos e identifique as principais tendências.
|
||||
|
||||
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.
|
||||
306
docs/edge/pt-BR/concepts/skills.mdx
Normal file
306
docs/edge/pt-BR/concepts/skills.mdx
Normal file
@@ -0,0 +1,306 @@
|
||||
---
|
||||
title: Skills
|
||||
description: Pacotes de skills baseados em sistema de arquivos que injetam expertise de domínio e instruções nos prompts dos agentes.
|
||||
icon: bolt
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Skills são diretórios autocontidos que fornecem aos agentes **instruções, diretrizes e material de referência específicos de domínio**. Cada skill é definida por um arquivo `SKILL.md` com frontmatter YAML e um corpo em markdown.
|
||||
|
||||
Quando ativada, as instruções de uma skill são injetadas diretamente no prompt da tarefa do agente — dando ao agente expertise sem exigir alterações de código.
|
||||
|
||||
<Note type="info" title="Skills vs Ferramentas — A Distinção Fundamental">
|
||||
**Skills NÃO são ferramentas.** Este é o ponto de confusão mais comum.
|
||||
|
||||
- **Skills** injetam *instruções e contexto* no prompt do agente. Elas dizem ao agente *como pensar* sobre um problema.
|
||||
- **Ferramentas** dão ao agente *funções chamáveis* para tomar ações (buscar, ler arquivos, chamar APIs).
|
||||
|
||||
Frequentemente você precisa de **ambos**: skills para expertise, ferramentas para ação. Eles são configurados independentemente e se complementam.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Início Rápido
|
||||
|
||||
### 1. Crie um Diretório de Skill
|
||||
|
||||
```
|
||||
skills/
|
||||
└── code-review/
|
||||
├── SKILL.md # Obrigatório — instruções
|
||||
├── references/ # Opcional — documentos de referência
|
||||
│ └── style-guide.md
|
||||
└── scripts/ # Opcional — scripts executáveis
|
||||
```
|
||||
|
||||
### 2. Escreva seu SKILL.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: code-review
|
||||
description: Guidelines for conducting thorough code reviews with focus on security and performance.
|
||||
metadata:
|
||||
author: your-team
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
## Diretrizes de Code Review
|
||||
|
||||
Ao revisar código, siga esta checklist:
|
||||
|
||||
1. **Segurança**: Verifique vulnerabilidades de injeção, bypasses de autenticação e exposição de dados
|
||||
2. **Performance**: Procure por queries N+1, alocações desnecessárias e chamadas bloqueantes
|
||||
3. **Legibilidade**: Garanta nomenclatura clara, comentários apropriados e estilo consistente
|
||||
4. **Testes**: Verifique cobertura adequada de testes para novas funcionalidades
|
||||
|
||||
### Níveis de Severidade
|
||||
- **Crítico**: Vulnerabilidades de segurança, riscos de perda de dados → bloquear merge
|
||||
- **Major**: Problemas de performance, erros de lógica → solicitar alterações
|
||||
- **Minor**: Questões de estilo, sugestões de nomenclatura → aprovar com comentários
|
||||
```
|
||||
|
||||
### 3. Anexe a um Agente
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai_tools import GithubSearchTool, FileReadTool
|
||||
|
||||
reviewer = Agent(
|
||||
role="Senior Code Reviewer",
|
||||
goal="Review pull requests for quality and security issues",
|
||||
backstory="Staff engineer with expertise in secure coding practices.",
|
||||
skills=["./skills"], # Injeta diretrizes de revisão
|
||||
tools=[GithubSearchTool(), FileReadTool()], # Permite ao agente ler código
|
||||
)
|
||||
```
|
||||
|
||||
O agente agora tem tanto **expertise** (da skill) quanto **capacidades** (das ferramentas).
|
||||
|
||||
---
|
||||
|
||||
## Skills + Ferramentas: Trabalhando Juntos
|
||||
|
||||
Aqui estão padrões comuns mostrando como skills e ferramentas se complementam:
|
||||
|
||||
### Padrão 1: Apenas Skills (Expertise de Domínio, Sem Ações Necessárias)
|
||||
|
||||
Use quando o agente precisa de instruções específicas mas não precisa chamar serviços externos:
|
||||
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Technical Writer",
|
||||
goal="Write clear API documentation",
|
||||
backstory="Expert technical writer",
|
||||
skills=["./skills/api-docs-style"], # Diretrizes e templates de escrita
|
||||
# Sem ferramentas necessárias — agente escreve baseado no contexto fornecido
|
||||
)
|
||||
```
|
||||
|
||||
### Padrão 2: Apenas Ferramentas (Ações, Sem Expertise Especial)
|
||||
|
||||
Use quando o agente precisa tomar ações mas não precisa de instruções específicas de domínio:
|
||||
|
||||
```python
|
||||
from crewai_tools import SerperDevTool, ScrapeWebsiteTool
|
||||
|
||||
agent = Agent(
|
||||
role="Web Researcher",
|
||||
goal="Find information about a topic",
|
||||
backstory="Skilled at finding information online",
|
||||
tools=[SerperDevTool(), ScrapeWebsiteTool()], # Pode buscar e extrair dados
|
||||
# Sem skills necessárias — pesquisa geral não precisa de diretrizes especiais
|
||||
)
|
||||
```
|
||||
|
||||
### Padrão 3: Skills + Ferramentas (Expertise E Ações)
|
||||
|
||||
O padrão mais comum no mundo real. A skill fornece *como* abordar o trabalho; ferramentas fornecem *o que* o agente pode fazer:
|
||||
|
||||
```python
|
||||
from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool
|
||||
|
||||
analyst = Agent(
|
||||
role="Security Analyst",
|
||||
goal="Audit infrastructure for vulnerabilities",
|
||||
backstory="Expert in cloud security and compliance",
|
||||
skills=["./skills/security-audit"], # Metodologia e checklists de auditoria
|
||||
tools=[
|
||||
SerperDevTool(), # Pesquisar vulnerabilidades conhecidas
|
||||
FileReadTool(), # Ler arquivos de configuração
|
||||
CodeInterpreterTool(), # Executar scripts de análise
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
### Padrão 4: Skills + MCPs
|
||||
|
||||
Skills funcionam junto com servidores MCP da mesma forma que com ferramentas:
|
||||
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze customer data and generate reports",
|
||||
backstory="Expert data analyst with strong statistical background",
|
||||
skills=["./skills/data-analysis"], # Metodologia de análise
|
||||
mcps=["https://data-warehouse.example.com/sse"], # Acesso remoto a dados
|
||||
)
|
||||
```
|
||||
|
||||
### Padrão 5: Skills + Apps
|
||||
|
||||
Skills podem guiar como um agente usa integrações de plataforma:
|
||||
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Customer Support Agent",
|
||||
goal="Respond to customer inquiries professionally",
|
||||
backstory="Experienced support representative",
|
||||
skills=["./skills/support-playbook"], # Templates de resposta e regras de escalação
|
||||
apps=["gmail", "zendesk"], # Pode enviar emails e atualizar tickets
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skills no Nível do Crew
|
||||
|
||||
Skills podem ser definidas no crew para aplicar a **todos os agentes**:
|
||||
|
||||
```python
|
||||
from crewai import Crew
|
||||
|
||||
crew = Crew(
|
||||
agents=[researcher, writer, reviewer],
|
||||
tasks=[research_task, write_task, review_task],
|
||||
skills=["./skills"], # Todos os agentes recebem essas skills
|
||||
)
|
||||
```
|
||||
|
||||
Skills no nível do agente têm prioridade — se a mesma skill é descoberta em ambos os níveis, a versão do agente é usada.
|
||||
|
||||
---
|
||||
|
||||
## Formato do SKILL.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: Descrição curta do que esta skill faz e quando usá-la.
|
||||
license: Apache-2.0 # opcional
|
||||
compatibility: crewai>=0.1.0 # opcional
|
||||
metadata: # opcional
|
||||
author: your-name
|
||||
version: "1.0"
|
||||
allowed-tools: web-search file-read # opcional, experimental
|
||||
---
|
||||
|
||||
Instruções para o agente vão aqui. Este corpo em markdown é injetado
|
||||
no prompt do agente quando a skill é ativada.
|
||||
```
|
||||
|
||||
### Campos do Frontmatter
|
||||
|
||||
| Campo | Obrigatório | Descrição |
|
||||
| :-------------- | :---------- | :----------------------------------------------------------------------- |
|
||||
| `name` | Sim | 1–64 chars. Alfanumérico minúsculo e hifens. Deve corresponder ao nome do diretório. |
|
||||
| `description` | Sim | 1–1024 chars. Descreve o que a skill faz e quando usá-la. |
|
||||
| `license` | Não | Nome da licença ou referência a um arquivo de licença incluído. |
|
||||
| `compatibility` | Não | Máx 500 chars. Requisitos de ambiente (produtos, pacotes, rede). |
|
||||
| `metadata` | Não | Mapeamento arbitrário de chave-valor string. |
|
||||
| `allowed-tools` | Não | Lista de ferramentas pré-aprovadas delimitada por espaços. Experimental. |
|
||||
|
||||
---
|
||||
|
||||
## Estrutura de Diretório
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Obrigatório — frontmatter + instruções
|
||||
├── scripts/ # Opcional — scripts executáveis
|
||||
├── references/ # Opcional — documentos de referência
|
||||
└── assets/ # Opcional — arquivos estáticos (configs, dados)
|
||||
```
|
||||
|
||||
O nome do diretório deve corresponder ao campo `name` no `SKILL.md`. Os diretórios `scripts/`, `references/` e `assets/` estão disponíveis no `path` da skill para agentes que precisam referenciar arquivos diretamente.
|
||||
|
||||
---
|
||||
|
||||
## Skills Pré-carregadas
|
||||
|
||||
Para mais controle, você pode descobrir e ativar skills programaticamente:
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
from crewai.skills import discover_skills, activate_skill
|
||||
|
||||
# Descobrir todas as skills em um diretório
|
||||
skills = discover_skills(Path("./skills"))
|
||||
|
||||
# Ativá-las (carrega o corpo completo do SKILL.md)
|
||||
activated = [activate_skill(s) for s in skills]
|
||||
|
||||
# Passar para um agente
|
||||
agent = Agent(
|
||||
role="Researcher",
|
||||
goal="Find relevant information",
|
||||
backstory="An expert researcher.",
|
||||
skills=activated,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Como as Skills São Carregadas
|
||||
|
||||
Skills usam **divulgação progressiva** — carregando apenas o necessário em cada estágio:
|
||||
|
||||
| Estágio | O que é carregado | Quando |
|
||||
| :--------- | :------------------------------------ | :------------------ |
|
||||
| Descoberta | Nome, descrição, campos do frontmatter | `discover_skills()` |
|
||||
| Ativação | Texto completo do corpo do SKILL.md | `activate_skill()` |
|
||||
|
||||
Durante a execução normal do agente (passando caminhos de diretório via `skills=["./skills"]`), skills são automaticamente descobertas e ativadas. O carregamento progressivo só importa quando usando a API programática.
|
||||
|
||||
---
|
||||
|
||||
## Skills vs Knowledge
|
||||
|
||||
Tanto skills quanto knowledge modificam o prompt do agente, mas servem propósitos diferentes:
|
||||
|
||||
| Aspecto | Skills | Knowledge |
|
||||
| :--- | :--- | :--- |
|
||||
| **O que fornece** | Instruções, procedimentos, diretrizes | Fatos, dados, informações |
|
||||
| **Como é armazenado** | Arquivos Markdown (SKILL.md) | Embarcado em banco vetorial (ChromaDB) |
|
||||
| **Como é recuperado** | Corpo inteiro injetado no prompt | Busca semântica encontra trechos relevantes |
|
||||
| **Melhor para** | Metodologia, checklists, guias de estilo | Documentos da empresa, info de produto, dados de referência |
|
||||
| **Definido via** | `skills=["./skills"]` | `knowledge_sources=[source]` |
|
||||
|
||||
**Regra prática:** Se o agente precisa seguir um *processo*, use uma skill. Se o agente precisa consultar *dados*, use knowledge.
|
||||
|
||||
---
|
||||
|
||||
## Perguntas Frequentes
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Preciso definir skills E ferramentas?">
|
||||
Depende do seu caso de uso. Skills e ferramentas são **independentes** — você pode usar qualquer um, ambos ou nenhum.
|
||||
|
||||
- **Apenas skills**: Quando o agente precisa de expertise mas não de ações externas (ex: escrever com diretrizes de estilo)
|
||||
- **Apenas ferramentas**: Quando o agente precisa de ações mas não de metodologia especial (ex: busca simples na web)
|
||||
- **Ambos**: Quando o agente precisa de expertise E ações (ex: auditoria de segurança com checklists específicas E capacidade de escanear código)
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Skills fornecem ferramentas automaticamente?">
|
||||
**Não.** O campo `allowed-tools` no SKILL.md é apenas metadado experimental — ele não provisiona nem injeta nenhuma ferramenta. Você deve sempre definir ferramentas separadamente via `tools=[]`, `mcps=[]` ou `apps=[]`.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="O que acontece se eu definir a mesma skill tanto no agente quanto no crew?">
|
||||
A skill no nível do agente tem prioridade. Skills são deduplicadas por nome — as skills do agente são processadas primeiro, então se o mesmo nome de skill aparece em ambos os níveis, a versão do agente é usada.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Qual o tamanho máximo do corpo do SKILL.md?">
|
||||
Há um aviso suave em 50.000 caracteres, mas sem limite rígido. Mantenha skills focadas e concisas para melhores resultados — injeções de prompt muito grandes podem diluir a atenção do agente.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
1105
docs/edge/pt-BR/concepts/tasks.mdx
Normal file
1105
docs/edge/pt-BR/concepts/tasks.mdx
Normal file
File diff suppressed because it is too large
Load Diff
49
docs/edge/pt-BR/concepts/testing.mdx
Normal file
49
docs/edge/pt-BR/concepts/testing.mdx
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: Testes
|
||||
description: Saiba como testar sua CrewAI Crew e avaliar seu desempenho.
|
||||
icon: vial
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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.
|
||||
292
docs/edge/pt-BR/concepts/tools.mdx
Normal file
292
docs/edge/pt-BR/concepts/tools.mdx
Normal file
@@ -0,0 +1,292 @@
|
||||
---
|
||||
title: Ferramentas
|
||||
description: Compreendendo e aproveitando ferramentas dentro do framework CrewAI para colaboração e execução de tarefas por agentes.
|
||||
icon: screwdriver-wrench
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
<Note type="info" title="Ferramentas são um dos cinco tipos de capacidades de agentes">
|
||||
Ferramentas dão aos agentes **funções chamáveis** para tomar ações. Elas funcionam junto com [MCPs](/pt-BR/mcp/overview) (servidores de ferramentas remotos), [Apps](/pt-BR/concepts/agent-capabilities) (integrações com plataformas), [Skills](/pt-BR/concepts/skills) (expertise de domínio) e [Knowledge](/pt-BR/concepts/knowledge) (fatos recuperados). Veja a visão geral de [Capacidades do Agente](/pt-BR/concepts/agent-capabilities) para entender quando usar cada um.
|
||||
</Note>
|
||||
|
||||
## 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 AMP 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='Analista de Mercado',
|
||||
goal='Fornecer análise de mercado atualizada da indústria de IA',
|
||||
backstory='Analista especialista com olhar atento para tendências de mercado.',
|
||||
tools=[search_tool, web_rag_tool],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role='Redator de Conteúdo',
|
||||
goal='Criar posts de blog envolventes sobre a indústria de IA',
|
||||
backstory='Redator habilidoso com paixão por tecnologia.',
|
||||
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/edge/pt-BR/concepts/training.mdx
Normal file
66
docs/edge/pt-BR/concepts/training.mdx
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Treinamento
|
||||
description: Aprenda como treinar seus agentes CrewAI fornecendo feedback desde o início e obtenha resultados consistentes.
|
||||
icon: dumbbell
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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_iteracoes = 2
|
||||
entradas = {"topic": "Treinamento CrewAI"}
|
||||
nome_arquivo = "seu_modelo.pkl"
|
||||
|
||||
try:
|
||||
SuaCrew().crew().train(
|
||||
n_iterations=n_iteracoes,
|
||||
inputs=entradas,
|
||||
filename=nome_arquivo
|
||||
)
|
||||
except Exception as e:
|
||||
raise Exception(f"Ocorreu um erro ao treinar a 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! 🚀
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: "Observe suas Automações"
|
||||
description: "Acompanhe a saúde da frota, o consumo de LLM e o comportamento por automação a partir da aba Automações."
|
||||
sidebarTitle: "Monitoramento"
|
||||
icon: "gauge"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Info>
|
||||
**Navegação da Documentação do ACP (Beta)**
|
||||
|
||||
- [Visão Geral](/pt-BR/enterprise/features/agent-control-plane/overview)
|
||||
- **Monitoramento** *(você está aqui)*
|
||||
- [Regras](/pt-BR/enterprise/features/agent-control-plane/rules)
|
||||
</Info>
|
||||
|
||||
## Visão Geral
|
||||
|
||||
A aba **Automações** é a visão de operações somente leitura do [Agent Control Plane](/pt-BR/enterprise/features/agent-control-plane/overview). Ela combina dois cards de métricas, um sankey interativo e duas sub-tabelas — **Automações** e **Consumo** — nas quais você pode buscar, filtrar e ordenar.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
Todos os gráficos e tabelas respeitam o seletor **Últimas 24 horas / Última Semana / Últimos 30 dias** no canto superior direito. As variações comparam a janela selecionada com a janela anterior de mesma duração.
|
||||
|
||||
<Note>
|
||||
As linhas só mostram dados de deployments em **crewAI v1.13 ou superior** — deployments mais antigos aparecem no banner *"We've detected N other automations that we can't display"* abaixo do sankey e não contribuem com nenhuma métrica até que sejam atualizados e re-implantados. Veja [Visão Geral — Requisitos](/pt-BR/enterprise/features/agent-control-plane/overview#requisitos).
|
||||
</Note>
|
||||
|
||||
## Dashboard
|
||||
|
||||
O topo da página tem dois cards de métricas e um sankey interativo. Clicar em qualquer um dos cards alterna o sankey entre dois modos:
|
||||
|
||||
- **Modo Saúde** — `Total de Automações → buckets de status (Critical / Warning / Healthy)`. Clique em um bucket para filtrar a tabela Automações para esses deployments.
|
||||
- **Modo Consumo** — `Provedores de Modelo → Automações → Custo Total`. Clique em um provedor para filtrar a tabela Consumo para esse provedor.
|
||||
|
||||
| Card | O que mostra |
|
||||
|------|---------------|
|
||||
| **Automações** | Automações `active` (e total), total de `errors` na janela, `active executions` no momento (e total na janela), com variação em relação ao período anterior. |
|
||||
| **Consumo** | `cost` total e `tokens used`, com variação de custo em relação ao período anterior. |
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Tabela de Automações
|
||||
|
||||
A sub-aba **Automações** é o detalhamento por deployment da saúde da frota. Cada linha é uma crew ou flow implantada.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
| Coluna | O que mostra |
|
||||
|--------|---------------|
|
||||
| **Automação** | Nome do deployment e quaisquer tags atribuídas a ele (ex.: `production`, `financial`). |
|
||||
| **Última execução** | Tempo decorrido desde a execução mais recente. |
|
||||
| **Health Status Breakdown** | Barra empilhada com percentuais de `Critical` / `Warning` / `Healthy` para as execuções na janela. |
|
||||
| **Executions with Errors** | Total de execuções com falha na janela. |
|
||||
| **PII detection applied** | `Yes` se houver configuração de PII por deployment ou uma [regra de PII](/pt-BR/enterprise/features/agent-control-plane/rules) correspondente ativa. |
|
||||
| **Executions** | Total de execuções na janela. |
|
||||
| **Last updated** | Quando o deployment foi re-implantado pela última vez. |
|
||||
| **Crew Version** | A versão do `crewai` reportada pelo deployment. Um ícone de informação ao lado de versões abaixo de `1.13` indica linhas que não conseguem contribuir com métricas. |
|
||||
|
||||
Busque por nome, filtre por `Status` (`Healthy` / `Warning` / `Critical`) e ordene por qualquer cabeçalho de coluna. Clique no nome de um deployment para abrir o **painel da Automação**.
|
||||
|
||||
## Tabela de Consumo
|
||||
|
||||
A sub-aba **Consumo** é o detalhamento por deployment de gasto com LLM e uso de tokens.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
| Coluna | O que mostra |
|
||||
|--------|---------------|
|
||||
| **Automação** | Nome do deployment. |
|
||||
| **Última execução** | Tempo decorrido desde a execução mais recente. |
|
||||
| **Tokens used** | Uma linha por provedor de LLM usado por esta automação, com variação em relação ao período anterior. |
|
||||
| **Cost** | Custo por provedor de LLM, com variação em relação ao período anterior. |
|
||||
| **Total cost** | Soma entre todos os provedores, com a variação. |
|
||||
| **Executions** | Total de execuções na janela. |
|
||||
| **Last updated** | Quando o deployment foi re-implantado pela última vez. |
|
||||
| **Crew Version** | A versão do `crewai` reportada pelo deployment. |
|
||||
|
||||
Filtre por **LLM provider** e ordene por `Cost`, `Executions` ou `Last run`.
|
||||
|
||||
<Info>
|
||||
**Células vazias (`—` ou `$0.00`) normalmente significam que o deployment está abaixo do crewAI v1.13.** Na captura acima, *Automation F* (`1.7.0`) e *Automation I* (`1.12.2`) mostram valores em branco para tokens e custo — suas execuções ainda rodam, mas não emitem a telemetria a nível de provedor que alimenta esta tabela. Atualize e re-implante essas crews para começar a coletar dados de consumo.
|
||||
</Info>
|
||||
|
||||
## Relacionados
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Agent Control Plane — Visão Geral" icon="book-open" href="/pt-BR/enterprise/features/agent-control-plane/overview">
|
||||
O que é o ACP, requisitos, planos suportados e RBAC.
|
||||
</Card>
|
||||
<Card title="Agent Control Plane — Regras" icon="shield-check" href="/pt-BR/enterprise/features/agent-control-plane/rules">
|
||||
Aplique regras de PII Redaction em nível de organização em muitas automações.
|
||||
</Card>
|
||||
<Card title="Traces" icon="timeline" href="/pt-BR/enterprise/features/traces">
|
||||
Aprofunde em uma única execução para ver o raciocínio do agente, chamadas de ferramentas e uso de tokens.
|
||||
</Card>
|
||||
<Card title="Deploy no AMP" icon="rocket" href="/pt-BR/enterprise/guides/deploy-to-amp">
|
||||
Implante uma crew em uma versão do crewAI que suporta o Agent Control Plane.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Card title="Precisa de ajuda?" icon="headset" href="mailto:support@crewai.com">
|
||||
Entre em contato com nosso time de suporte para ajudar a interpretar métricas no Agent Control Plane.
|
||||
</Card>
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: Visão Geral do Agent Control Plane
|
||||
description: "Hub único de operações para automações ao vivo — saúde da frota, consumo de LLM e políticas em nível de organização em um só lugar."
|
||||
sidebarTitle: Visão Geral
|
||||
icon: "book-open"
|
||||
---
|
||||
|
||||
<Info>
|
||||
**Navegação da Documentação do ACP (Beta)**
|
||||
|
||||
- **Visão Geral** *(você está aqui)*
|
||||
- [Monitoramento](/pt-BR/enterprise/features/agent-control-plane/monitoring)
|
||||
- [Regras](/pt-BR/enterprise/features/agent-control-plane/rules)
|
||||
</Info>
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O **Agent Control Plane** (ACP) é o hub de operações para tudo que você tem rodando no CrewAI AMP. É uma tela única — dividida nas abas **Automações** e **Regras** — que permite à sua equipe:
|
||||
|
||||
- Monitorar a **saúde** de cada automação ao vivo (crew ou flow), com detalhamentos `Critical` / `Warning` / `Healthy` e contagem de execuções.
|
||||
- Acompanhar o **consumo de LLM** — tokens e custo — por automação, por provedor e por modelo, com a variação em relação ao período anterior.
|
||||
- Aprofundar em qualquer automação ou provedor de modelo para ver gráficos de série temporal e detalhamentos por provedor.
|
||||
- Aplicar **Regras** em nível de organização (hoje: PII Redaction) em muitas automações de uma só vez, em vez de editar cada deployment individualmente.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
<Note>
|
||||
O Agent Control Plane está atualmente marcado como **Beta** na CrewAI Platform.
|
||||
</Note>
|
||||
|
||||
As duas abas respondem a duas perguntas distintas:
|
||||
|
||||
- **Automações** — *"Como minha frota está se comportando agora e quanto está me custando?"* Veja [Monitoramento](/pt-BR/enterprise/features/agent-control-plane/monitoring).
|
||||
- **Regras** — *"Como aplico uma política (por exemplo, PII redaction) em muitos deployments sem precisar reimplantar cada um?"* Veja [Regras](/pt-BR/enterprise/features/agent-control-plane/rules).
|
||||
|
||||
## Requisitos
|
||||
|
||||
<Warning>
|
||||
**crewAI v1.13 ou superior** é necessário para que uma automação preencha qualquer dado nesta página — saúde, execuções, erros, tokens e custo passam por telemetria que foi habilitada em `crewai==1.13`. Deployments mais antigos aparecem no banner *"We've detected N other automations that we can't display"* e não contribuem com nenhum dado até que sejam atualizados e re-implantados.
|
||||
</Warning>
|
||||
|
||||
<Warning>
|
||||
**Plano Enterprise ou Ultra** é necessário para criar ou editar [Regras](/pt-BR/enterprise/features/agent-control-plane/rules). Organizações em planos inferiores ainda podem abrir a aba Regras e visualizar regras existentes, mas o editor é renderizado em modo somente leitura, com um selo "Enterprise" de bloqueio e o alerta *"PII Redaction rules require an Enterprise plan."* O Monitoramento (a aba Automações) está disponível em todos os planos em que o recurso esteja habilitado.
|
||||
</Warning>
|
||||
|
||||
- O recurso **Agent Control Plane** precisa estar habilitado para sua organização. Se você não o vê na barra lateral, peça ao owner da conta para solicitar a habilitação.
|
||||
- Dentro do ACP, o [RBAC](/pt-BR/enterprise/features/rbac) controla o acesso: `read` para visualizar o dashboard e as regras, `manage` para criar, editar, ligar/desligar ou excluir regras.
|
||||
- Todos os gráficos e tabelas podem ser ajustados para **Últimas 24 horas**, **Última Semana** ou **Últimos 30 dias** usando o seletor de tempo no canto superior direito. As variações (`↑ 8 vs ontem`, `↓ $20.57 vs ontem`, etc.) comparam a janela selecionada com a janela anterior de mesma duração.
|
||||
|
||||
## O que você pode fazer aqui
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Monitoramento" icon="gauge" href="/pt-BR/enterprise/features/agent-control-plane/monitoring">
|
||||
Acompanhe a saúde da frota e o gasto com LLM com cards de métricas, um sankey interativo, tabelas por automação e painéis laterais de detalhamento para qualquer automação ou provedor.
|
||||
</Card>
|
||||
<Card title="Regras" icon="shield-check" href="/pt-BR/enterprise/features/agent-control-plane/rules">
|
||||
Aplique políticas de PII Redaction em nível de organização, com escopo por ferramentas e tags. As mudanças entram em vigor na próxima execução — sem necessidade de re-implantação.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Relacionados
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Traces" icon="timeline" href="/pt-BR/enterprise/features/traces">
|
||||
Aprofunde em uma única execução para ver o raciocínio do agente, chamadas de ferramentas e uso de tokens.
|
||||
</Card>
|
||||
<Card title="RBAC" icon="users" href="/pt-BR/enterprise/features/rbac">
|
||||
Gerencie quem pode ler o Agent Control Plane e quem pode editar regras.
|
||||
</Card>
|
||||
<Card title="PII Redaction para Traces" icon="lock" href="/pt-BR/enterprise/features/pii-trace-redactions">
|
||||
Catálogo de entidades e configuração de PII por deployment, referenciados pelas Regras.
|
||||
</Card>
|
||||
<Card title="Deploy no AMP" icon="rocket" href="/pt-BR/enterprise/guides/deploy-to-amp">
|
||||
Implante uma crew em uma versão do crewAI que suporta o Agent Control Plane.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Card title="Precisa de ajuda?" icon="headset" href="mailto:support@crewai.com">
|
||||
Entre em contato com nosso time de suporte para interpretar métricas ou desenhar regras.
|
||||
</Card>
|
||||
@@ -0,0 +1,122 @@
|
||||
---
|
||||
title: "Configure as Regras"
|
||||
description: "Aplique políticas em nível de organização em muitas automações a partir de um único lugar."
|
||||
sidebarTitle: "Regras"
|
||||
icon: "shield-check"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Info>
|
||||
**Navegação da Documentação do ACP (Beta)**
|
||||
|
||||
- [Visão Geral](/pt-BR/enterprise/features/agent-control-plane/overview)
|
||||
- [Monitoramento](/pt-BR/enterprise/features/agent-control-plane/monitoring)
|
||||
- **Regras** *(você está aqui)*
|
||||
</Info>
|
||||
|
||||
## Visão Geral
|
||||
|
||||
As Regras permitem aplicar políticas — hoje: **PII Redaction** — em muitas automações de uma só vez, em vez de configurar cada deployment individualmente. Abra a aba **Regras** no [Agent Control Plane](/pt-BR/enterprise/features/agent-control-plane/overview) para gerenciá-las.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
Cada card de regra mostra o nome, a descrição, o **escopo** ao qual a regra se aplica (ferramentas e tags selecionadas) e a contagem de **automações engajadas** — deployments que atualmente correspondem ao escopo. O toggle à direita ativa ou desativa a regra sem excluí-la.
|
||||
|
||||
## Requisitos
|
||||
|
||||
<Warning>
|
||||
**Plano Enterprise ou Ultra** é necessário para criar ou editar regras de PII Redaction. Organizações em planos inferiores ainda podem abrir a aba Regras e visualizar regras existentes, mas o editor é renderizado em modo somente leitura, com um selo "Enterprise" de bloqueio e o alerta *"PII Redaction rules require an Enterprise plan."* — entre em contato com o owner da sua conta ou com vendas para fazer upgrade.
|
||||
</Warning>
|
||||
|
||||
- O recurso **Agent Control Plane** precisa estar habilitado para sua organização. Veja [Visão Geral — Requisitos](/pt-BR/enterprise/features/agent-control-plane/overview#requisitos).
|
||||
- A permissão `manage` no [RBAC](/pt-BR/enterprise/features/rbac) sobre o Agent Control Plane é necessária para criar, editar, ligar/desligar ou excluir regras. A permissão `read` é suficiente para visualizá-las.
|
||||
- Todas as mudanças de regras são versionadas para auditoria.
|
||||
|
||||
## Tipos de regra disponíveis
|
||||
|
||||
| Tipo | O que faz |
|
||||
|------|---------------|
|
||||
| **PII Redaction** | Aplica PII redaction às execuções de cada automação correspondente, usando o mesmo catálogo de entidades e recognizers customizados documentados em [PII Redaction para Traces](/pt-BR/enterprise/features/pii-trace-redactions). |
|
||||
|
||||
Mais tipos de regras serão adicionados ao longo do tempo.
|
||||
|
||||
## Criando uma regra
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/acp-rules-edit-side-panel.png" alt="Painel lateral de edição de regra com condições e tipo de máscara de PII" width="450" />
|
||||
</Frame>
|
||||
|
||||
<Steps>
|
||||
<Step title="Abra o editor">
|
||||
Clique em **+ Create new** no canto superior direito da aba Regras, ou em **View Details** em um card de regra existente.
|
||||
</Step>
|
||||
|
||||
<Step title="Dê um nome e descreva a regra">
|
||||
Dê à regra um nome claro (ex.: *Mask PII (CC)*) e uma descrição explicando quando ela se aplica. Ambos aparecem no card da regra e no modal de Automações Engajadas.
|
||||
</Step>
|
||||
|
||||
<Step title="Escolha o tipo">
|
||||
Hoje só **PII Redaction** está disponível.
|
||||
</Step>
|
||||
|
||||
<Step title="Defina as condições">
|
||||
As condições decidem quais automações a regra engaja. Ambas são opcionais e usam a semântica de **igualdade de conjuntos**:
|
||||
|
||||
- **Tools** — apenas automações cujo conjunto de ferramentas **corresponde exatamente** às ferramentas selecionadas serão engajadas. Selecione entre apps do Studio, MCPs, ferramentas OSS e ferramentas do Tool Repository.
|
||||
- **Automations** — apenas automações cujo conjunto de tags **corresponde exatamente** às tags selecionadas serão engajadas.
|
||||
|
||||
Deixar um seletor vazio significa "sem filtro nesta dimensão". Deixar ambos vazios significa que a regra se aplica a **todas** as automações da organização.
|
||||
</Step>
|
||||
|
||||
<Step title="Configure a tabela PII Mask Type">
|
||||
Marque cada tipo de entidade que deseja cobrir e escolha **Mask** (substitui pelo rótulo da entidade, ex.: `<CREDIT_CARD>`) ou **Redact** (remove o texto correspondente por completo). Veja [PII Redaction para Traces](/pt-BR/enterprise/features/pii-trace-redactions) para o catálogo completo de entidades e como adicionar recognizers customizados em nível de organização.
|
||||
</Step>
|
||||
|
||||
<Step title="Salve">
|
||||
A regra se aplica a **futuras** execuções de cada automação engajada assim que você salva. Nenhuma re-implantação é necessária.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Automações engajadas
|
||||
|
||||
Clique em **Engaged N automations** em qualquer card de regra para ver exatamente quais deployments a regra está correspondendo no momento, junto com a última execução de cada um.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
Esta é a forma mais rápida de validar o escopo de uma regra antes de habilitá-la — por exemplo, para confirmar que uma regra com escopo na tag `production` não está acidentalmente correspondendo a um deployment de staging.
|
||||
|
||||
## Regras em nível de organização vs configurações por deployment
|
||||
|
||||
A PII Redaction pode ser configurada em dois lugares:
|
||||
|
||||
- **Por deployment** — em **Settings → PII Protection** em cada deployment individual ([guia](/pt-BR/enterprise/features/pii-trace-redactions))
|
||||
- **Em nível de organização** — como uma Regra nesta página
|
||||
|
||||
Quando o escopo de uma regra habilitada em nível de organização corresponde a um deployment, a configuração de entidades da regra **sobrescreve** as configurações de PII pertencentes ao deployment para as execuções daquele deployment — a regra se torna a fonte única da verdade enquanto está vinculada. Desabilite ou desvincule a regra (ou altere o escopo para que ela não corresponda mais) e o deployment volta às suas próprias configurações de PII Protection.
|
||||
|
||||
Prefira regras em nível de organização quando quiser impor uma política consistente em muitos deployments; reserve a configuração por deployment para exceções pontuais.
|
||||
|
||||
## Relacionados
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Agent Control Plane — Visão Geral" icon="book-open" href="/pt-BR/enterprise/features/agent-control-plane/overview">
|
||||
O que é o ACP, requisitos, planos suportados e RBAC.
|
||||
</Card>
|
||||
<Card title="Agent Control Plane — Monitoramento" icon="gauge" href="/pt-BR/enterprise/features/agent-control-plane/monitoring">
|
||||
Acompanhe automações e consumo de LLM em toda a sua frota.
|
||||
</Card>
|
||||
<Card title="PII Redaction para Traces" icon="lock" href="/pt-BR/enterprise/features/pii-trace-redactions">
|
||||
Catálogo de entidades, recognizers customizados e configuração por deployment.
|
||||
</Card>
|
||||
<Card title="RBAC" icon="users" href="/pt-BR/enterprise/features/rbac">
|
||||
Gerencie quem pode criar ou editar regras.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Card title="Precisa de ajuda?" icon="headset" href="mailto:support@crewai.com">
|
||||
Entre em contato com nosso time de suporte para ajudar a desenhar regras para a sua organização.
|
||||
</Card>
|
||||
156
docs/edge/pt-BR/enterprise/features/agent-repositories.mdx
Normal file
156
docs/edge/pt-BR/enterprise/features/agent-repositories.mdx
Normal file
@@ -0,0 +1,156 @@
|
||||
---
|
||||
title: 'Repositórios de Agentes'
|
||||
description: 'Aprenda a usar Repositórios de Agentes para compartilhar e reutilizar seus agentes entre equipes e projetos'
|
||||
icon: 'database'
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
Repositórios de Agentes permitem que usuários do enterprise armazenem, compartilhem e reutilizem definições de agentes entre equipes e projetos. Esse recurso possibilita manter uma biblioteca centralizada de agentes padronizados, promovendo consistência e reduzindo a duplicidade de esforços.
|
||||
|
||||
## Benefícios dos Repositórios de Agentes
|
||||
|
||||
- **Padronização**: Mantenha definições de agentes consistentes em toda a sua organização
|
||||
- **Reutilização**: Crie um agente uma vez e use-o em vários crews e projetos
|
||||
- **Governança**: Implemente políticas organizacionais para configurações de agentes
|
||||
- **Colaboração**: Permita que equipes compartilhem e evoluam o trabalho umas das outras
|
||||
|
||||
## Usando Repositórios de Agentes
|
||||
|
||||
### Pré-requisitos
|
||||
|
||||
1. Você deve ter uma conta na CrewAI, experimente o [plano gratuito](https://app.crewai.com).
|
||||
2. Você precisa estar autenticado usando o CLI da CrewAI.
|
||||
3. Se você tiver mais de uma organização, garanta que alternou para a organização correta usando o comando do CLI:
|
||||
|
||||
```bash
|
||||
crewai org switch <org_id>
|
||||
```
|
||||
|
||||
### Criando e gerenciando agentes em repositórios
|
||||
|
||||
Para criar e gerenciar agentes em repositórios, utilize o Painel do Enterprise.
|
||||
|
||||
### Carregando agentes de repositórios
|
||||
|
||||
Você pode carregar agentes de repositórios no seu código usando o parâmetro `from_repository`:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
|
||||
# Crie um agente carregando-o de um repositório
|
||||
# O agente é carregado com todas as suas configurações predefinidas
|
||||
researcher = Agent(
|
||||
from_repository="market-research-agent"
|
||||
)
|
||||
|
||||
```
|
||||
|
||||
### Sobrescrevendo configurações do repositório
|
||||
|
||||
Você pode sobrescrever configurações específicas do repositório informando-as na configuração do agente:
|
||||
|
||||
```python
|
||||
researcher = Agent(
|
||||
from_repository="market-research-agent",
|
||||
goal="Pesquisar as tendências mais recentes em desenvolvimento de IA", # Sobrescreve o goal do repositório
|
||||
verbose=True # Adiciona uma configuração que não está no repositório
|
||||
)
|
||||
```
|
||||
|
||||
### Exemplo: criando um Crew com agentes do repositório
|
||||
|
||||
```python
|
||||
from crewai import Crew, Agent, Task
|
||||
|
||||
# Carregue agentes dos repositórios
|
||||
researcher = Agent(
|
||||
from_repository="market-research-agent"
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
from_repository="content-writer-agent"
|
||||
)
|
||||
|
||||
# Crie tarefas
|
||||
research_task = Task(
|
||||
description="Pesquise as tendências mais recentes em IA",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
writing_task = Task(
|
||||
description="Escreva um relatório abrangente com base na pesquisa",
|
||||
agent=writer
|
||||
)
|
||||
|
||||
# Crie o crew
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, writing_task],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Execute o crew
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
### Exemplo: usando `kickoff()` com agentes do repositório
|
||||
|
||||
Você também pode usar agentes de repositório diretamente com o método `kickoff()` para interações mais simples:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from pydantic import BaseModel
|
||||
from typing import List
|
||||
|
||||
# Defina um formato de saída estruturado
|
||||
class MarketAnalysis(BaseModel):
|
||||
key_trends: List[str]
|
||||
opportunities: List[str]
|
||||
recommendation: str
|
||||
|
||||
# Carregue um agente do repositório
|
||||
analyst = Agent(
|
||||
from_repository="market-analyst-agent",
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Obtenha uma resposta livre (texto)
|
||||
result = analyst.kickoff("Analise o mercado de IA em 2025")
|
||||
print(result.raw) # Acessa a resposta bruta
|
||||
|
||||
# Obtenha saída estruturada
|
||||
structured_result = analyst.kickoff(
|
||||
"Forneça uma análise estruturada do mercado de IA em 2025",
|
||||
response_format=MarketAnalysis
|
||||
)
|
||||
|
||||
# Acesse os dados estruturados
|
||||
print(f"Principais Tendências: {structured_result.pydantic.key_trends}")
|
||||
print(f"Recomendação: {structured_result.pydantic.recommendation}")
|
||||
```
|
||||
|
||||
## Boas práticas
|
||||
|
||||
1. **Convenção de nomes**: Use nomes claros e descritivos para seus agentes de repositório
|
||||
2. **Documentação**: Inclua descrições abrangentes para cada agente
|
||||
3. **Gestão de ferramentas**: Garanta que as ferramentas referenciadas pelos agentes do repositório estejam disponíveis no seu ambiente
|
||||
4. **Controle de acesso**: Gerencie permissões para que apenas membros autorizados possam modificar agentes do repositório
|
||||
|
||||
## Gerenciamento de organização
|
||||
|
||||
Para alternar entre organizações ou ver sua organização atual, use o CLI da CrewAI:
|
||||
|
||||
```bash
|
||||
# Ver organização atual
|
||||
crewai org current
|
||||
|
||||
# Alternar para outra organização
|
||||
crewai org switch <org_id>
|
||||
|
||||
# Listar todas as organizações disponíveis
|
||||
crewai org list
|
||||
```
|
||||
|
||||
<Note>
|
||||
Ao carregar agentes de repositórios, você deve estar autenticado e ter alternado para a organização correta. Se você receber erros, verifique seu status de autenticação e as configurações de organização usando os comandos do CLI acima.
|
||||
</Note>
|
||||
103
docs/edge/pt-BR/enterprise/features/automations.mdx
Normal file
103
docs/edge/pt-BR/enterprise/features/automations.mdx
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
title: "Automações"
|
||||
description: "Gerencie, implante e monitore seus crews (automações) em um só lugar."
|
||||
icon: "rocket"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão geral
|
||||
|
||||
Automações é o hub operacional para seus crews implantados. Use para implantar via GitHub ou arquivo ZIP, gerenciar variáveis de ambiente, reimplantar quando necessário e monitorar o status de cada automação.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Métodos de implantação
|
||||
|
||||
### Implantar via GitHub
|
||||
|
||||
Use para projetos versionados e implantação contínua.
|
||||
|
||||
<Steps>
|
||||
<Step title="Conectar GitHub">
|
||||
Clique em <b>Configure GitHub</b> e autorize o acesso.
|
||||
</Step>
|
||||
<Step title="Selecionar Repositório & Branch">
|
||||
Escolha o <b>Repositório</b> e a <b>Branch</b> que deseja implantar.
|
||||
</Step>
|
||||
<Step title="Ativar Auto‑deploy (opcional)">
|
||||
Ative <b>Automatically deploy new commits</b> para publicar a cada push.
|
||||
</Step>
|
||||
<Step title="Adicionar Variáveis de Ambiente">
|
||||
Adicione segredos individualmente ou use <b>Bulk View</b> para múltiplas variáveis.
|
||||
</Step>
|
||||
<Step title="Implantar">
|
||||
Clique em <b>Deploy</b> para criar sua automação.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
### Implantar via ZIP
|
||||
|
||||
Envie rapidamente sem Git — faça upload de um pacote ZIP do projeto.
|
||||
|
||||
<Steps>
|
||||
<Step title="Escolher arquivo">
|
||||
Selecione o arquivo ZIP do seu computador.
|
||||
</Step>
|
||||
<Step title="Adicionar Variáveis de Ambiente">
|
||||
Informe as variáveis necessárias.
|
||||
</Step>
|
||||
<Step title="Implantar">
|
||||
Clique em <b>Deploy</b> para criar sua automação.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Painel de Automações
|
||||
|
||||
A tabela lista todas as automações com detalhes chave:
|
||||
|
||||
- **CREW**: Nome da automação
|
||||
- **STATUS**: Online / Failed / In Progress
|
||||
- **URL**: Endpoint para kickoff/status
|
||||
- **TOKEN**: Token da automação
|
||||
- **ACTIONS**: Re‑deploy, delete e outros
|
||||
|
||||
Use os controles no canto superior direito para filtrar e pesquisar:
|
||||
|
||||
- Pesquisar por nome
|
||||
- Filtrar por <b>Status</b>
|
||||
- Filtrar por <b>Source</b> (GitHub / Studio / ZIP)
|
||||
|
||||
Após implantar, você pode ver os detalhes da automação e usar o menu **Options** para `chat with this crew`, `Export React Component` e `Export as MCP`.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Boas práticas
|
||||
|
||||
- Prefira implantações via GitHub para controle de versão e CI/CD
|
||||
- Use re‑deploy para avançar após mudanças de código/config ou habilite auto‑deploy a cada push
|
||||
|
||||
## Relacionados
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Implantar um Crew" href="/pt-BR/enterprise/guides/deploy-to-amp" icon="rocket">
|
||||
Implante um Crew via GitHub ou arquivo ZIP.
|
||||
</Card>
|
||||
<Card title="Gatilhos de Automação" href="/pt-BR/enterprise/guides/automation-triggers" icon="trigger">
|
||||
Dispare automações por webhooks ou API.
|
||||
</Card>
|
||||
<Card title="Automação com Webhook" href="/pt-BR/enterprise/guides/webhook-automation" icon="webhook">
|
||||
Transmita eventos e atualizações em tempo real.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
88
docs/edge/pt-BR/enterprise/features/crew-studio.mdx
Normal file
88
docs/edge/pt-BR/enterprise/features/crew-studio.mdx
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: "Crew Studio"
|
||||
description: "Crie novas automações com assistência de IA, editor visual e testes integrados."
|
||||
icon: "pencil"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão geral
|
||||
|
||||
O Crew Studio é um espaço interativo com assistência de IA para criar novas automações do zero usando linguagem natural e um editor visual de fluxo de trabalho.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Criação baseada em prompts
|
||||
|
||||
- Descreva a automação desejada; a IA gera agentes, tarefas e ferramentas.
|
||||
- Use entrada por voz pelo ícone de microfone se preferir.
|
||||
- Comece com prompts prontos para casos comuns.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Editor Visual
|
||||
|
||||
O canvas reflete o fluxo como nós e arestas com três painéis de suporte que permitem configurar o fluxo sem escrever código ("vibe coding AI Agents"):
|
||||
|
||||
- **AI Thoughts (esquerda)**: raciocínio em tempo real enquanto o fluxo é projetado
|
||||
- **Canvas (centro)**: agentes e tarefas como nós conectados
|
||||
- **Resources (direita)**: componentes de arrastar‑e‑soltar (agentes, tarefas, ferramentas)
|
||||
|
||||
Você pode arrastar e soltar agentes, tarefas e ferramentas no canvas ou usar a seção de chat para construir os agentes. Ambos compartilham estado e podem ser usados de forma intercambiável.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Execução & Depuração
|
||||
|
||||
Alterne para a visão <b>Execution</b> para executar e observar o fluxo:
|
||||
|
||||
- Linha do tempo de eventos
|
||||
- Logs detalhados (Details, Messages, Raw Data)
|
||||
- Execuções locais antes de publicar
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Publicar & Exportar
|
||||
|
||||
- <b>Publish</b> para implantar uma automação
|
||||
- <b>Download</b> do código‑fonte como ZIP para desenvolvimento local
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
Após publicar, você pode visualizar os detalhes da automação e usar o menu **Options** para `chat with this crew`, `Export React Component` e `Export as MCP`.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Boas práticas
|
||||
|
||||
- Itere rapidamente no Studio; publique apenas quando estiver estável
|
||||
- Restrinja permissões das ferramentas ao mínimo necessário
|
||||
- Use Traces para validar comportamento e desempenho
|
||||
|
||||
## Relacionados
|
||||
|
||||
<CardGroup cols={4}>
|
||||
<Card title="Habilitar o Crew Studio" href="/pt-BR/enterprise/guides/enable-crew-studio" icon="palette">
|
||||
Habilite o Crew Studio.
|
||||
</Card>
|
||||
<Card title="Criar um Crew" href="/pt-BR/enterprise/guides/build-crew" icon="paintbrush">
|
||||
Crie um Crew.
|
||||
</Card>
|
||||
<Card title="Implantar um Crew" href="/pt-BR/enterprise/guides/deploy-to-amp" icon="rocket">
|
||||
Implante um Crew via GitHub ou ZIP.
|
||||
</Card>
|
||||
<Card title="Exportar um Componente React" href="/pt-BR/enterprise/guides/react-component-export" icon="download">
|
||||
Exporte um componente React.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
558
docs/edge/pt-BR/enterprise/features/flow-hitl-management.mdx
Normal file
558
docs/edge/pt-BR/enterprise/features/flow-hitl-management.mdx
Normal file
@@ -0,0 +1,558 @@
|
||||
---
|
||||
title: "Gerenciamento HITL para Flows"
|
||||
description: "Revisão humana de nível empresarial para Flows com notificações por email, regras de roteamento e capacidades de resposta automática"
|
||||
icon: "users-gear"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Os recursos de gerenciamento HITL para Flows requerem o decorador `@human_feedback`, disponível no **CrewAI versão 1.8.0 ou superior**. Estes recursos aplicam-se especificamente a **Flows**, não a Crews.
|
||||
</Note>
|
||||
|
||||
O CrewAI Enterprise oferece um sistema abrangente de gerenciamento Human-in-the-Loop (HITL) para Flows que transforma fluxos de trabalho de IA em processos colaborativos humano-IA. A plataforma usa uma **arquitetura email-first** que permite que qualquer pessoa com um endereço de email responda a solicitações de revisão—sem necessidade de conta na plataforma.
|
||||
|
||||
## Visão Geral
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Design Email-First" icon="envelope">
|
||||
Respondentes podem responder diretamente aos emails de notificação para fornecer feedback
|
||||
</Card>
|
||||
<Card title="Roteamento Flexível" icon="route">
|
||||
Direcione solicitações para emails específicos com base em padrões de método ou estado do flow
|
||||
</Card>
|
||||
<Card title="Resposta Automática" icon="clock">
|
||||
Configure respostas automáticas de fallback quando nenhum humano responder a tempo
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Principais Benefícios
|
||||
|
||||
- **Modelo mental simples**: Endereços de email são universais; não é necessário gerenciar usuários ou funções da plataforma
|
||||
- **Respondentes externos**: Qualquer pessoa com email pode responder, mesmo não sendo usuário da plataforma
|
||||
- **Atribuição dinâmica**: Obtenha o email do responsável diretamente do estado do flow (ex: `sales_rep_email`)
|
||||
- **Configuração reduzida**: Menos configurações para definir, tempo mais rápido para gerar valor
|
||||
- **Email como canal principal**: A maioria dos usuários prefere responder via email do que fazer login em um dashboard
|
||||
|
||||
## Configurando Pontos de Revisão Humana em Flows
|
||||
|
||||
Configure checkpoints de revisão humana em seus Flows usando o decorador `@human_feedback`. Quando a execução atinge um ponto de revisão, o sistema pausa, notifica o responsável via email e aguarda uma resposta.
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, start, listen, or_
|
||||
from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult
|
||||
|
||||
class ContentApprovalFlow(Flow):
|
||||
@start()
|
||||
def generate_content(self):
|
||||
return "Texto de marketing gerado para campanha Q1..."
|
||||
|
||||
@human_feedback(
|
||||
message="Por favor, revise este conteúdo para conformidade com a marca:",
|
||||
emit=["approved", "rejected", "needs_revision"],
|
||||
)
|
||||
@listen(or_("generate_content", "needs_revision"))
|
||||
def review_content(self):
|
||||
return "Texto de marketing para revisão..."
|
||||
|
||||
@listen("approved")
|
||||
def publish_content(self, result: HumanFeedbackResult):
|
||||
print(f"Publicando conteúdo aprovado. Notas do revisor: {result.feedback}")
|
||||
|
||||
@listen("rejected")
|
||||
def archive_content(self, result: HumanFeedbackResult):
|
||||
print(f"Conteúdo rejeitado. Motivo: {result.feedback}")
|
||||
```
|
||||
|
||||
Para detalhes completos de implementação, consulte o guia [Feedback Humano em Flows](/pt-BR/learn/human-feedback-in-flows).
|
||||
|
||||
### Parâmetros do Decorador
|
||||
|
||||
| Parâmetro | Tipo | Descrição |
|
||||
|-----------|------|-----------|
|
||||
| `message` | `str` | A mensagem exibida para o revisor humano |
|
||||
| `emit` | `list[str]` | Opções de resposta válidas (exibidas como botões na UI) |
|
||||
|
||||
## Configuração da Plataforma
|
||||
|
||||
Acesse a configuração HITL em: **Deployment** → **Settings** → **Human in the Loop Configuration**
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/hitl-settings-overview.png" alt="Configurações HITL" />
|
||||
</Frame>
|
||||
|
||||
### Notificações por Email
|
||||
|
||||
Toggle para ativar ou desativar notificações por email para solicitações HITL.
|
||||
|
||||
| Configuração | Padrão | Descrição |
|
||||
|--------------|--------|-----------|
|
||||
| Notificações por Email | Ativado | Enviar emails quando feedback for solicitado |
|
||||
|
||||
<Note>
|
||||
Quando desativado, os respondentes devem usar a UI do dashboard ou você deve configurar webhooks para sistemas de notificação personalizados.
|
||||
</Note>
|
||||
|
||||
### Meta de SLA
|
||||
|
||||
Defina um tempo de resposta alvo para fins de rastreamento e métricas.
|
||||
|
||||
| Configuração | Descrição |
|
||||
|--------------|-----------|
|
||||
| Meta de SLA (minutos) | Tempo de resposta alvo. Usado para métricas do dashboard e rastreamento de SLA |
|
||||
|
||||
Deixe vazio para desativar o rastreamento de SLA.
|
||||
|
||||
## Notificações e Respostas por Email
|
||||
|
||||
O sistema HITL usa uma arquitetura email-first onde os respondentes podem responder diretamente aos emails de notificação.
|
||||
|
||||
### Como Funcionam as Respostas por Email
|
||||
|
||||
<Steps>
|
||||
<Step title="Notificação Enviada">
|
||||
Quando uma solicitação HITL é criada, um email é enviado ao respondente atribuído com o conteúdo e contexto da revisão.
|
||||
</Step>
|
||||
<Step title="Endereço Reply-To">
|
||||
O email inclui um endereço reply-to especial com um token assinado para autenticação.
|
||||
</Step>
|
||||
<Step title="Usuário Responde">
|
||||
O respondente simplesmente responde ao email com seu feedback—nenhum login necessário.
|
||||
</Step>
|
||||
<Step title="Validação do Token">
|
||||
A plataforma recebe a resposta, verifica o token assinado e corresponde o email do remetente.
|
||||
</Step>
|
||||
<Step title="Flow Continua">
|
||||
O feedback é registrado e o flow continua com a entrada humana.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Formato de Resposta
|
||||
|
||||
Respondentes podem responder com:
|
||||
|
||||
- **Opção emit**: Se a resposta corresponder a uma opção `emit` (ex: "approved"), ela é usada diretamente
|
||||
- **Texto livre**: Qualquer resposta de texto é passada para o flow como feedback
|
||||
- **Texto simples**: A primeira linha do corpo da resposta é usada como feedback
|
||||
|
||||
### Emails de Confirmação
|
||||
|
||||
Após processar uma resposta, o respondente recebe um email de confirmação indicando se o feedback foi enviado com sucesso ou se ocorreu um erro.
|
||||
|
||||
### Segurança do Token de Email
|
||||
|
||||
- Tokens são assinados criptograficamente para segurança
|
||||
- Tokens expiram após 7 dias
|
||||
- Email do remetente deve corresponder ao email autorizado do token
|
||||
- Emails de confirmação/erro são enviados após o processamento
|
||||
|
||||
## Regras de Roteamento
|
||||
|
||||
Direcione solicitações HITL para endereços de email específicos com base em padrões de método.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/hitl-settings-routing-rules.png" alt="Configuração de Regras de Roteamento HITL" />
|
||||
</Frame>
|
||||
|
||||
### Estrutura da Regra
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Aprovações para Financeiro",
|
||||
"match": {
|
||||
"method_name": "approve_*"
|
||||
},
|
||||
"assign_to_email": "financeiro@empresa.com",
|
||||
"assign_from_input": "manager_email"
|
||||
}
|
||||
```
|
||||
|
||||
### Padrões de Correspondência
|
||||
|
||||
| Padrão | Descrição | Exemplo de Correspondência |
|
||||
|--------|-----------|---------------------------|
|
||||
| `approve_*` | Wildcard (qualquer caractere) | `approve_payment`, `approve_vendor` |
|
||||
| `review_?` | Caractere único | `review_a`, `review_1` |
|
||||
| `validate_payment` | Correspondência exata | apenas `validate_payment` |
|
||||
|
||||
### Prioridade de Atribuição
|
||||
|
||||
1. **Atribuição dinâmica** (`assign_from_input`): Se configurado, obtém email do estado do flow
|
||||
2. **Email estático** (`assign_to_email`): Fallback para email configurado
|
||||
3. **Criador do deployment**: Se nenhuma regra corresponder, o email do criador do deployment é usado
|
||||
|
||||
### Exemplo de Atribuição Dinâmica
|
||||
|
||||
Se seu estado do flow contém `{"sales_rep_email": "alice@empresa.com"}`, configure:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Direcionar para Representante de Vendas",
|
||||
"match": {
|
||||
"method_name": "review_*"
|
||||
},
|
||||
"assign_from_input": "sales_rep_email"
|
||||
}
|
||||
```
|
||||
|
||||
A solicitação será atribuída automaticamente para `alice@empresa.com`.
|
||||
|
||||
<Tip>
|
||||
**Caso de Uso**: Obtenha o responsável do seu CRM, banco de dados ou etapa anterior do flow para direcionar revisões dinamicamente para a pessoa certa.
|
||||
</Tip>
|
||||
|
||||
## Resposta Automática
|
||||
|
||||
Responda automaticamente a solicitações HITL se nenhum humano responder dentro do timeout. Isso garante que os flows não fiquem travados indefinidamente.
|
||||
|
||||
### Configuração
|
||||
|
||||
| Configuração | Descrição |
|
||||
|--------------|-----------|
|
||||
| Ativado | Toggle para ativar resposta automática |
|
||||
| Timeout (minutos) | Tempo de espera antes de responder automaticamente |
|
||||
| Resultado Padrão | O valor da resposta (deve corresponder a uma opção `emit`) |
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/hitl-settings-auto-respond.png" alt="Configuração de Resposta Automática HITL" />
|
||||
</Frame>
|
||||
|
||||
### Casos de Uso
|
||||
|
||||
- **Conformidade com SLA**: Garante que flows não fiquem travados indefinidamente
|
||||
- **Aprovação padrão**: Aprove automaticamente solicitações de baixo risco após timeout
|
||||
- **Degradação graciosa**: Continue com um padrão seguro quando revisores não estiverem disponíveis
|
||||
|
||||
<Warning>
|
||||
Use resposta automática com cuidado. Ative apenas para revisões não críticas onde uma resposta padrão é aceitável.
|
||||
</Warning>
|
||||
|
||||
## Processo de Revisão
|
||||
|
||||
### Interface do Dashboard
|
||||
|
||||
A interface de revisão HITL oferece uma experiência limpa e focada para revisores:
|
||||
|
||||
- **Renderização Markdown**: Formatação rica para conteúdo de revisão com destaque de sintaxe
|
||||
- **Painel de Contexto**: Visualize estado do flow, histórico de execução e informações relacionadas
|
||||
- **Entrada de Feedback**: Forneça feedback detalhado e comentários com sua decisão
|
||||
- **Ações Rápidas**: Botões de opção emit com um clique com comentários opcionais
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/hitl-list-pending-feedbacks.png" alt="Lista de Solicitações HITL Pendentes" />
|
||||
</Frame>
|
||||
|
||||
### Métodos de Resposta
|
||||
|
||||
Revisores podem responder por três canais:
|
||||
|
||||
| Método | Descrição |
|
||||
|--------|-----------|
|
||||
| **Resposta por Email** | Responda diretamente ao email de notificação |
|
||||
| **Dashboard** | Use a UI do dashboard Enterprise |
|
||||
| **API/Webhook** | Resposta programática via API |
|
||||
|
||||
### Histórico e Trilha de Auditoria
|
||||
|
||||
Toda interação HITL é rastreada com uma linha do tempo completa:
|
||||
|
||||
- Histórico de decisões (aprovar/rejeitar/revisar)
|
||||
- Identidade do revisor e timestamp
|
||||
- Feedback e comentários fornecidos
|
||||
- Método de resposta (email/dashboard/API)
|
||||
- Métricas de tempo de resposta
|
||||
|
||||
## Análise e Monitoramento
|
||||
|
||||
Acompanhe o desempenho HITL com análises abrangentes.
|
||||
|
||||
### Dashboard de Desempenho
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/hitl-metrics.png" alt="Dashboard de Métricas HITL" />
|
||||
</Frame>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Tempos de Resposta" icon="stopwatch">
|
||||
Monitore tempos de resposta médios e medianos por revisor ou flow.
|
||||
</Card>
|
||||
<Card title="Tendências de Volume" icon="chart-bar">
|
||||
Analise padrões de volume de revisão para otimizar capacidade da equipe.
|
||||
</Card>
|
||||
<Card title="Distribuição de Decisões" icon="chart-pie">
|
||||
Visualize taxas de aprovação/rejeição em diferentes tipos de revisão.
|
||||
</Card>
|
||||
<Card title="Rastreamento de SLA" icon="chart-line">
|
||||
Acompanhe a porcentagem de revisões concluídas dentro das metas de SLA.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Auditoria e Conformidade
|
||||
|
||||
Capacidades de auditoria prontas para empresas para requisitos regulatórios:
|
||||
|
||||
- Histórico completo de decisões com timestamps
|
||||
- Verificação de identidade do revisor
|
||||
- Logs de auditoria imutáveis
|
||||
- Capacidades de exportação para relatórios de conformidade
|
||||
|
||||
## Casos de Uso Comuns
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Revisões de Segurança" icon="shield-halved">
|
||||
**Caso de Uso**: Automação de questionários de segurança internos com validação humana
|
||||
|
||||
- IA gera respostas para questionários de segurança
|
||||
- Equipe de segurança revisa e valida precisão via email
|
||||
- Respostas aprovadas são compiladas na submissão final
|
||||
- Trilha de auditoria completa para conformidade
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Aprovação de Conteúdo" icon="file-lines">
|
||||
**Caso de Uso**: Conteúdo de marketing que requer revisão legal/marca
|
||||
|
||||
- IA gera texto de marketing ou conteúdo de mídia social
|
||||
- Roteie para email da equipe de marca para revisão de voz/tom
|
||||
- Publicação automática após aprovação
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Aprovações Financeiras" icon="money-bill">
|
||||
**Caso de Uso**: Relatórios de despesas, termos de contrato, alocações de orçamento
|
||||
|
||||
- IA pré-processa e categoriza solicitações financeiras
|
||||
- Roteie com base em limites de valor usando atribuição dinâmica
|
||||
- Mantenha trilha de auditoria completa para conformidade financeira
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Atribuição Dinâmica do CRM" icon="database">
|
||||
**Caso de Uso**: Direcione revisões para proprietários de conta do seu CRM
|
||||
|
||||
- Flow obtém email do proprietário da conta do CRM
|
||||
- Armazene email no estado do flow (ex: `account_owner_email`)
|
||||
- Use `assign_from_input` para direcionar automaticamente para a pessoa certa
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Garantia de Qualidade" icon="magnifying-glass">
|
||||
**Caso de Uso**: Validação de saída de IA antes da entrega ao cliente
|
||||
|
||||
- IA gera conteúdo ou respostas voltadas ao cliente
|
||||
- Equipe de QA revisa via notificação por email
|
||||
- Loops de feedback melhoram desempenho da IA ao longo do tempo
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## API de Webhooks
|
||||
|
||||
Quando seus Flows pausam para feedback humano, você pode configurar webhooks para enviar dados da solicitação para sua própria aplicação. Isso permite:
|
||||
|
||||
- Construir UIs de aprovação personalizadas
|
||||
- Integrar com ferramentas internas (Jira, ServiceNow, dashboards personalizados)
|
||||
- Rotear aprovações para sistemas de terceiros
|
||||
- Notificações em apps mobile
|
||||
- Sistemas de decisão automatizados
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/hitl-settings-webhook.png" alt="Configuração de Webhook HITL" />
|
||||
</Frame>
|
||||
|
||||
### Configurando Webhooks
|
||||
|
||||
<Steps>
|
||||
<Step title="Navegue até Configurações">
|
||||
Vá para **Deployment** → **Settings** → **Human in the Loop**
|
||||
</Step>
|
||||
<Step title="Expanda a Seção Webhooks">
|
||||
Clique para expandir a configuração de **Webhooks**
|
||||
</Step>
|
||||
<Step title="Adicione sua URL de Webhook">
|
||||
Digite sua URL de webhook (deve ser HTTPS em produção)
|
||||
</Step>
|
||||
<Step title="Salve a Configuração">
|
||||
Clique em **Salvar Configuração** para ativar
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Você pode configurar múltiplos webhooks. Cada webhook ativo recebe todos os eventos HITL.
|
||||
|
||||
### Eventos de Webhook
|
||||
|
||||
Seu endpoint receberá requisições HTTP POST para estes eventos:
|
||||
|
||||
| Tipo de Evento | Quando é Disparado |
|
||||
|----------------|-------------------|
|
||||
| `new_request` | Um flow pausa e solicita feedback humano |
|
||||
|
||||
### Payload do Webhook
|
||||
|
||||
Todos os webhooks recebem um payload JSON com esta estrutura:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "new_request",
|
||||
"request": {
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"flow_id": "flow_abc123",
|
||||
"method_name": "review_article",
|
||||
"message": "Por favor, revise este artigo para publicação.",
|
||||
"emit_options": ["approved", "rejected", "request_changes"],
|
||||
"state": {
|
||||
"article_id": 12345,
|
||||
"author": "john@example.com",
|
||||
"category": "technology"
|
||||
},
|
||||
"metadata": {},
|
||||
"created_at": "2026-01-14T12:00:00Z"
|
||||
},
|
||||
"deployment": {
|
||||
"id": 456,
|
||||
"name": "Content Review Flow",
|
||||
"organization_id": 789
|
||||
},
|
||||
"callback_url": "https://api.crewai.com/...",
|
||||
"assigned_to_email": "reviewer@company.com"
|
||||
}
|
||||
```
|
||||
|
||||
### Respondendo a Solicitações
|
||||
|
||||
Para enviar feedback, **faça POST para a `callback_url`** incluída no payload do webhook.
|
||||
|
||||
```http
|
||||
POST {callback_url}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"feedback": "Aprovado. Ótimo artigo!",
|
||||
"source": "my_custom_app"
|
||||
}
|
||||
```
|
||||
|
||||
### Segurança
|
||||
|
||||
<Info>
|
||||
Todas as requisições de webhook são assinadas criptograficamente usando HMAC-SHA256 para garantir autenticidade e prevenir adulteração.
|
||||
</Info>
|
||||
|
||||
#### Segurança do Webhook
|
||||
|
||||
- **Assinaturas HMAC-SHA256**: Todo webhook inclui uma assinatura criptográfica
|
||||
- **Secrets por webhook**: Cada webhook tem seu próprio secret de assinatura único
|
||||
- **Criptografado em repouso**: Os secrets de assinatura são criptografados no nosso banco de dados
|
||||
- **Verificação de timestamp**: Previne ataques de replay
|
||||
|
||||
#### Headers de Assinatura
|
||||
|
||||
Cada requisição de webhook inclui estes headers:
|
||||
|
||||
| Header | Descrição |
|
||||
|--------|-----------|
|
||||
| `X-Signature` | Assinatura HMAC-SHA256: `sha256=<hex_digest>` |
|
||||
| `X-Timestamp` | Timestamp Unix de quando a requisição foi assinada |
|
||||
|
||||
#### Verificação
|
||||
|
||||
Verifique computando:
|
||||
|
||||
```python
|
||||
import hmac
|
||||
import hashlib
|
||||
|
||||
expected = hmac.new(
|
||||
signing_secret.encode(),
|
||||
f"{timestamp}.{payload}".encode(),
|
||||
hashlib.sha256
|
||||
).hexdigest()
|
||||
|
||||
if hmac.compare_digest(expected, signature):
|
||||
# Assinatura válida
|
||||
```
|
||||
|
||||
### Tratamento de Erros
|
||||
|
||||
Seu endpoint de webhook deve retornar um código de status 2xx para confirmar o recebimento:
|
||||
|
||||
| Sua Resposta | Nosso Comportamento |
|
||||
|--------------|---------------------|
|
||||
| 2xx | Webhook entregue com sucesso |
|
||||
| 4xx/5xx | Registrado como falha, sem retry |
|
||||
| Timeout (30s) | Registrado como falha, sem retry |
|
||||
|
||||
## Segurança e RBAC
|
||||
|
||||
### Acesso ao Dashboard
|
||||
|
||||
O acesso HITL é controlado no nível do deployment:
|
||||
|
||||
| Permissão | Capacidade |
|
||||
|-----------|------------|
|
||||
| `manage_human_feedback` | Configurar settings HITL, ver todas as solicitações |
|
||||
| `respond_to_human_feedback` | Responder a solicitações, ver solicitações atribuídas |
|
||||
|
||||
### Autorização de Resposta por Email
|
||||
|
||||
Para respostas por email:
|
||||
1. O token reply-to codifica o email autorizado
|
||||
2. Email do remetente deve corresponder ao email do token
|
||||
3. Token não deve estar expirado (padrão 7 dias)
|
||||
4. Solicitação ainda deve estar pendente
|
||||
|
||||
### Trilha de Auditoria
|
||||
|
||||
Todas as ações HITL são registradas:
|
||||
- Criação de solicitação
|
||||
- Mudanças de atribuição
|
||||
- Submissão de resposta (com fonte: dashboard/email/API)
|
||||
- Status de retomada do flow
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Emails Não Enviando
|
||||
|
||||
1. Verifique se "Notificações por Email" está ativado na configuração
|
||||
2. Verifique se as regras de roteamento correspondem ao nome do método
|
||||
3. Verifique se o email do responsável é válido
|
||||
4. Verifique o fallback do criador do deployment se nenhuma regra de roteamento corresponder
|
||||
|
||||
### Respostas de Email Não Processando
|
||||
|
||||
1. Verifique se o token não expirou (padrão 7 dias)
|
||||
2. Verifique se o email do remetente corresponde ao email atribuído
|
||||
3. Garanta que a solicitação ainda está pendente (não respondida ainda)
|
||||
|
||||
### Flow Não Retomando
|
||||
|
||||
1. Verifique o status da solicitação no dashboard
|
||||
2. Verifique se a URL de callback está acessível
|
||||
3. Garanta que o deployment ainda está rodando
|
||||
|
||||
## Melhores Práticas
|
||||
|
||||
<Tip>
|
||||
**Comece Simples**: Comece com notificações por email para o criador do deployment, depois adicione regras de roteamento conforme seus fluxos de trabalho amadurecem.
|
||||
</Tip>
|
||||
|
||||
1. **Use Atribuição Dinâmica**: Obtenha emails de responsáveis do seu estado do flow para roteamento flexível.
|
||||
|
||||
2. **Configure Resposta Automática**: Defina um fallback para revisões não críticas para evitar que flows fiquem travados.
|
||||
|
||||
3. **Monitore Tempos de Resposta**: Use análises para identificar gargalos e otimizar seu processo de revisão.
|
||||
|
||||
4. **Mantenha Mensagens de Revisão Claras**: Escreva mensagens claras e acionáveis no decorador `@human_feedback`.
|
||||
|
||||
5. **Teste o Fluxo de Email**: Envie solicitações de teste para verificar a entrega de email antes de ir para produção.
|
||||
|
||||
## Recursos Relacionados
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Feedback Humano em Flows" icon="code" href="/pt-BR/learn/human-feedback-in-flows">
|
||||
Guia de implementação para o decorador `@human_feedback`
|
||||
</Card>
|
||||
<Card title="Guia de Workflow HITL para Flows" icon="route" href="/pt-BR/enterprise/guides/human-in-the-loop">
|
||||
Guia passo a passo para configurar workflows HITL
|
||||
</Card>
|
||||
<Card title="Configuração RBAC" icon="shield-check" href="/pt-BR/enterprise/features/rbac">
|
||||
Configure controle de acesso baseado em função para sua organização
|
||||
</Card>
|
||||
<Card title="Streaming de Webhook" icon="bolt" href="/pt-BR/enterprise/features/webhook-streaming">
|
||||
Configure notificações de eventos em tempo real
|
||||
</Card>
|
||||
</CardGroup>
|
||||
251
docs/edge/pt-BR/enterprise/features/hallucination-guardrail.mdx
Normal file
251
docs/edge/pt-BR/enterprise/features/hallucination-guardrail.mdx
Normal file
@@ -0,0 +1,251 @@
|
||||
---
|
||||
title: Proteção contra Alucinações
|
||||
description: "Previna e detecte alucinações de IA nas suas tarefas do CrewAI"
|
||||
icon: "shield-check"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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
|
||||
protecao = HallucinationGuardrail(
|
||||
llm=LLM(model="gpt-4o-mini")
|
||||
)
|
||||
|
||||
# Com contexto de referência explícito
|
||||
protecao_com_contexto = HallucinationGuardrail(
|
||||
context="IA ajuda em várias tarefas, incluindo análise e geração.",
|
||||
llm=LLM(model="gpt-4o-mini")
|
||||
)
|
||||
```
|
||||
|
||||
### Adicionando às Tarefas
|
||||
|
||||
```python
|
||||
from crewai import Task
|
||||
|
||||
# Crie sua tarefa com a proteção
|
||||
minha_tarefa = Task(
|
||||
description="Escreva um resumo sobre as capacidades da IA",
|
||||
expected_output="Um resumo factual baseado no contexto fornecido",
|
||||
agent=meu_agente,
|
||||
guardrail=protecao # 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
|
||||
protecao_rigorosa = HallucinationGuardrail(
|
||||
context="Computação quântica utiliza qubits que existem em estados de superposição.",
|
||||
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
|
||||
protecao_clima = HallucinationGuardrail(
|
||||
context="Informações meteorológicas atuais para o local solicitado",
|
||||
llm=LLM(model="gpt-4o-mini"),
|
||||
tool_response="API do Clima retornou: Temperatura 22°C, Umidade 65%, Céu limpo"
|
||||
)
|
||||
```
|
||||
|
||||
## 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 = meu_agente.execute_task(minha_tarefa)
|
||||
resultado_validacao = protecao(task_output)
|
||||
|
||||
if resultado_validacao.valid:
|
||||
# Tarefa concluída com sucesso
|
||||
return task_output
|
||||
else:
|
||||
# Tarefa falha com feedback de validação
|
||||
raise ValidationError(resultado_validacao.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
|
||||
contexto = """
|
||||
Empresa XYZ foi fundada em 2020 e é especializada em soluções de energia renovável.
|
||||
Possui 150 funcionários e faturou R$ 50 milhões em 2023.
|
||||
Seus principais produtos incluem painéis solares e turbinas eólicas.
|
||||
"""
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Mantenha o Contexto Relevante">
|
||||
Inclua apenas informações diretamente relacionadas à tarefa para evitar confusão:
|
||||
|
||||
```python
|
||||
# Bom: Contexto focado
|
||||
contexto = "O clima atual em Nova York é 18°C com chuva leve."
|
||||
|
||||
# Evite: Informações irrelevantes
|
||||
contexto = "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>
|
||||
45
docs/edge/pt-BR/enterprise/features/marketplace.mdx
Normal file
45
docs/edge/pt-BR/enterprise/features/marketplace.mdx
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: "Marketplace"
|
||||
description: "Descubra, instale e governe ativos reutilizáveis para seus crews enterprise."
|
||||
icon: "store"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão geral
|
||||
|
||||
O Marketplace oferece uma superfície curada para descobrir integrações, ferramentas internas e ativos reutilizáveis que aceleram o desenvolvimento de crews.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Descoberta
|
||||
|
||||
- Navegue por categoria e capacidade
|
||||
- Pesquise por nome ou palavra‑chave
|
||||
|
||||
## Instalar & Habilitar
|
||||
|
||||
- Instalação com um clique para ativos aprovados
|
||||
- Habilite ou desabilite por crew conforme necessário
|
||||
- Configure variáveis de ambiente e escopos necessários
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
Você também pode baixar templates diretamente do marketplace clicando em `Download` para usar localmente ou personalizar conforme necessário.
|
||||
|
||||
## Relacionados
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Ferramentas & Integrações" href="/pt-BR/enterprise/features/tools-and-integrations" icon="wrench">
|
||||
Conecte apps externos e gerencie ferramentas internas que seus agentes podem usar.
|
||||
</Card>
|
||||
<Card title="Repositório de Ferramentas" href="/pt-BR/enterprise/guides/tool-repository" icon="toolbox">
|
||||
Publique e instale ferramentas para ampliar as capacidades dos seus crews.
|
||||
</Card>
|
||||
<Card title="Repositório de Agentes" href="/pt-BR/enterprise/features/agent-repositories" icon="people-group">
|
||||
Armazene, compartilhe e reutilize definições de agentes entre equipes e projetos.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
342
docs/edge/pt-BR/enterprise/features/pii-trace-redactions.mdx
Normal file
342
docs/edge/pt-BR/enterprise/features/pii-trace-redactions.mdx
Normal file
@@ -0,0 +1,342 @@
|
||||
---
|
||||
title: Redação de PII para Traces
|
||||
description: "Redija automaticamente dados sensíveis de traces de execução de crews e flows"
|
||||
icon: "lock"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
A Redação de PII é um recurso do CrewAI AMP que detecta e mascara automaticamente Informações de Identificação Pessoal (PII) nos traces de execução de crews e flows. Isso garante que dados sensíveis como números de cartão de crédito, CPF, endereços de e-mail e nomes não sejam expostos nos traces do CrewAI AMP. Você também pode criar reconhecedores personalizados para proteger dados específicos da sua organização.
|
||||
|
||||
|
||||
<Info>
|
||||
A Redação de PII está disponível no plano Enterprise.
|
||||
A implantação deve ser versão 1.8.0 ou superior.
|
||||
</Info>
|
||||
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
|
||||
## Por Que a Redação de PII é Importante
|
||||
|
||||
Ao executar agentes de IA em produção, informações sensíveis frequentemente fluem através das suas crews:
|
||||
|
||||
- Dados de clientes de integrações CRM
|
||||
- Informações financeiras de processadores de pagamento
|
||||
- Detalhes pessoais de envios de formulários
|
||||
- Dados internos de funcionários
|
||||
|
||||
Sem a redação adequada, esses dados aparecem nos traces, tornando a conformidade com regulamentações como LGPD, HIPAA e PCI-DSS desafiadora. A Redação de PII resolve isso mascarando automaticamente dados sensíveis antes de serem armazenados nos traces.
|
||||
|
||||
## Como Funciona
|
||||
|
||||
1. **Detectar** - Escanear dados de eventos de trace para padrões de PII conhecidos
|
||||
2. **Classificar** - Identificar o tipo de dado sensível (cartão de crédito, CPF, e-mail, etc.)
|
||||
3. **Mascarar/Redigir** - Substituir os dados sensíveis por valores mascarados com base na sua configuração
|
||||
|
||||
```
|
||||
Original: "Entre em contato com john.doe@company.com ou ligue para 555-123-4567"
|
||||
Redigido: "Entre em contato com <EMAIL_ADDRESS> ou ligue para <PHONE_NUMBER>"
|
||||
```
|
||||
|
||||
## Habilitando a Redação de PII
|
||||
|
||||
<Info>
|
||||
Você deve estar no plano Enterprise e sua implantação deve ser versão 1.8.0 ou superior para usar este recurso.
|
||||
</Info>
|
||||
|
||||
<Steps>
|
||||
<Step title="Navegue até Configurações da Crew">
|
||||
No painel do CrewAI AMP, selecione sua crew implantada e vá para uma de suas implantações/automações, depois navegue até **Settings** → **PII Protection**.
|
||||
</Step>
|
||||
|
||||
<Step title="Habilitar Proteção PII">
|
||||
Ative **PII Redaction for Traces**. Isso habilitará a varredura automática e redação de dados de trace.
|
||||
|
||||
<Info>
|
||||
Você precisa habilitar manualmente a Redação de PII para cada implantação.
|
||||
</Info>
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="Configurar Tipos de Entidade">
|
||||
Selecione quais tipos de PII detectar e redigir. Cada entidade pode ser habilitada ou desabilitada individualmente.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="Salvar">
|
||||
Salve sua configuração. A redação de PII estará ativa em todas as execuções subsequentes da crew, sem necessidade de reimplantação.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Tipos de Entidade Suportados
|
||||
|
||||
O CrewAI suporta os seguintes tipos de entidade PII, organizados por categoria.
|
||||
|
||||
### Entidades Globais
|
||||
|
||||
| Entidade | Descrição | Exemplo |
|
||||
|----------|-----------|---------|
|
||||
| `CREDIT_CARD` | Números de cartão de crédito/débito | "4111-1111-1111-1111" |
|
||||
| `CRYPTO` | Endereços de carteira de criptomoedas | "bc1qxy2kgd..." |
|
||||
| `DATE_TIME` | Datas e horários | "15 de janeiro de 2024" |
|
||||
| `EMAIL_ADDRESS` | Endereços de e-mail | "john@example.com" |
|
||||
| `IBAN_CODE` | Números de conta bancária internacional | "DE89 3704 0044 0532 0130 00" |
|
||||
| `IP_ADDRESS` | Endereços IPv4 e IPv6 | "192.168.1.1" |
|
||||
| `LOCATION` | Localizações geográficas | "São Paulo" |
|
||||
| `MEDICAL_LICENSE` | Números de licença médica | "CRM12345" |
|
||||
| `NRP` | Nacionalidades, grupos religiosos ou políticos | - |
|
||||
| `PERSON` | Nomes pessoais | "João Silva" |
|
||||
| `PHONE_NUMBER` | Números de telefone em vários formatos | "+55 (11) 98765-4321" |
|
||||
| `URL` | URLs da web | "https://example.com" |
|
||||
|
||||
### Entidades Específicas dos EUA
|
||||
|
||||
| Entidade | Descrição | Exemplo |
|
||||
|----------|-----------|---------|
|
||||
| `US_BANK_NUMBER` | Números de conta bancária dos EUA | "1234567890" |
|
||||
| `US_DRIVER_LICENSE` | Números de carteira de motorista dos EUA | "D1234567" |
|
||||
| `US_ITIN` | Número de Identificação de Contribuinte Individual | "900-70-0000" |
|
||||
| `US_PASSPORT` | Números de passaporte dos EUA | "123456789" |
|
||||
| `US_SSN` | Números de Seguro Social | "123-45-6789" |
|
||||
|
||||
## Ações de Redação
|
||||
|
||||
Para cada entidade habilitada, você pode configurar como os dados são redigidos:
|
||||
|
||||
| Ação | Descrição | Exemplo de Saída |
|
||||
|------|-----------|------------------|
|
||||
| `mask` | Substituir pelo rótulo do tipo de entidade | `<CREDIT_CARD>` |
|
||||
| `redact` | Remover completamente o texto | *(vazio)* |
|
||||
|
||||
## Reconhecedores Personalizados
|
||||
|
||||
Além das entidades integradas, você pode criar **reconhecedores personalizados** para detectar padrões de PII específicos da sua organização.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
### Tipos de Reconhecedores
|
||||
|
||||
Você tem duas opções para reconhecedores personalizados:
|
||||
|
||||
| Tipo | Melhor Para | Exemplo de Caso de Uso |
|
||||
|------|-------------|------------------------|
|
||||
| **Baseado em Padrão (Regex)** | Dados estruturados com formatos previsíveis | Valores de salário, IDs de funcionários, códigos de projeto |
|
||||
| **Lista de Negação** | Correspondências exatas de strings | Nomes de empresas, codinomes internos, termos específicos |
|
||||
|
||||
### Criando um Reconhecedor Personalizado
|
||||
|
||||
<Steps>
|
||||
<Step title="Navegue até Reconhecedores Personalizados">
|
||||
Vá para **Settings** da Organização → **Organization** → **Add Recognizer**.
|
||||
</Step>
|
||||
|
||||
<Step title="Configure o Reconhecedor">
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
Configure os seguintes campos:
|
||||
- **Name**: Um nome descritivo para o reconhecedor
|
||||
- **Entity Type**: O rótulo da entidade que aparecerá na saída redigida (ex.: `EMPLOYEE_ID`, `SALARY`)
|
||||
- **Type**: Escolha entre Padrão Regex ou Lista de Negação
|
||||
- **Pattern/Values**: Padrão regex ou lista de strings para corresponder
|
||||
- **Confidence Threshold**: Pontuação mínima (0.0-1.0) necessária para uma correspondência acionar a redação. Valores mais altos (ex.: 0.8) reduzem falsos positivos, mas podem perder algumas correspondências. Valores mais baixos (ex.: 0.5) capturam mais correspondências, mas podem redigir em excesso. O padrão é 0.8.
|
||||
- **Context Words** (opcional): Palavras que aumentam a confiança de detecção quando encontradas próximas
|
||||
</Step>
|
||||
|
||||
<Step title="Salvar">
|
||||
Salve o reconhecedor. Ele estará disponível para habilitar em suas implantações.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Entendendo os Tipos de Entidade
|
||||
|
||||
O **Entity Type** determina como o conteúdo correspondido aparece nos traces redigidos:
|
||||
|
||||
```
|
||||
Entity Type: SALARY
|
||||
Pattern: salary:\s*\$\s*\d+
|
||||
Entrada: "Salário do funcionário: $50,000"
|
||||
Saída: "Salário do funcionário <SALARY>"
|
||||
```
|
||||
|
||||
### Usando Palavras de Contexto
|
||||
|
||||
Palavras de contexto melhoram a precisão aumentando a confiança quando termos específicos aparecem próximos ao padrão correspondido:
|
||||
|
||||
```
|
||||
Context Words: "project", "code", "internal"
|
||||
Entity Type: PROJECT_CODE
|
||||
Pattern: PRJ-\d{4}
|
||||
```
|
||||
|
||||
Quando "project" ou "code" aparece próximo a "PRJ-1234", o reconhecedor tem maior confiança de que é uma correspondência verdadeira, reduzindo falsos positivos.
|
||||
|
||||
|
||||
## Visualizando Traces Redigidos
|
||||
|
||||
Uma vez que a redação de PII está habilitada, seus traces mostrarão valores redigidos no lugar de dados sensíveis:
|
||||
|
||||
```
|
||||
Task Output: "Cliente <PERSON> fez o pedido #12345.
|
||||
E-mail de contato: <EMAIL_ADDRESS>, telefone: <PHONE_NUMBER>.
|
||||
Pagamento processado para cartão terminando em <CREDIT_CARD>."
|
||||
```
|
||||
|
||||
Os valores redigidos são claramente marcados com colchetes angulares e o rótulo do tipo de entidade (ex.: `<EMAIL_ADDRESS>`), facilitando entender quais dados foram protegidos enquanto ainda permite depurar e monitorar o comportamento da crew.
|
||||
|
||||
|
||||
|
||||
## Melhores Práticas
|
||||
|
||||
### Considerações de Desempenho
|
||||
|
||||
<Steps>
|
||||
<Step title="Habilite Apenas Entidades Necessárias">
|
||||
Cada entidade habilitada adiciona sobrecarga de processamento. Habilite apenas entidades relevantes para seus dados.
|
||||
</Step>
|
||||
|
||||
<Step title="Use Padrões Específicos">
|
||||
Para reconhecedores personalizados, use padrões específicos para reduzir falsos positivos e melhorar o desempenho. Padrões regex são melhores para identificar padrões específicos nos traces como salário, ID de funcionário, código de projeto, etc. Reconhecedores de lista de negação são melhores para identificar strings exatas nos traces como nomes de empresas, codinomes internos, etc.
|
||||
</Step>
|
||||
|
||||
<Step title="Aproveite Palavras de Contexto">
|
||||
Palavras de contexto melhoram a precisão acionando a detecção apenas quando o texto circundante corresponde.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
<Accordion title="PII Não Está Sendo Redigido">
|
||||
**Possíveis Causas:**
|
||||
- Tipo de entidade não habilitado na configuração
|
||||
- Padrão não corresponde ao formato dos dados
|
||||
- Reconhecedor personalizado tem erros de sintaxe
|
||||
|
||||
**Soluções:**
|
||||
- Verifique se a entidade está habilitada em Settings → Security
|
||||
- Teste padrões regex com dados de amostra
|
||||
- Verifique logs para erros de configuração
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Muitos Dados Estão Sendo Redigidos">
|
||||
**Possíveis Causas:**
|
||||
- Tipos de entidade muito amplos habilitados (ex.: `DATE_TIME` captura datas em todos os lugares)
|
||||
- Padrões de reconhecedor personalizado são muito gerais
|
||||
|
||||
**Soluções:**
|
||||
- Desabilite entidades que causam falsos positivos
|
||||
- Torne padrões personalizados mais específicos
|
||||
- Adicione palavras de contexto para melhorar a precisão
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Problemas de Desempenho">
|
||||
**Possíveis Causas:**
|
||||
- Muitas entidades habilitadas
|
||||
- Entidades baseadas em NLP (`PERSON`, `LOCATION`, `NRP`) são computacionalmente caras pois usam modelos de machine learning
|
||||
|
||||
**Soluções:**
|
||||
- Habilite apenas entidades que você realmente precisa
|
||||
- Considere usar alternativas baseadas em padrão quando possível
|
||||
- Monitore tempos de processamento de trace no painel
|
||||
</Accordion>
|
||||
|
||||
---
|
||||
|
||||
## Exemplo Prático: Correspondência de Padrão de Salário
|
||||
|
||||
Este exemplo demonstra como criar um reconhecedor personalizado para detectar e mascarar informações de salário em seus traces.
|
||||
|
||||
### Caso de Uso
|
||||
|
||||
Sua crew processa dados de funcionários ou financeiros que incluem informações de salário em formatos como:
|
||||
- `salary: $50,000`
|
||||
- `salary: $125,000.00`
|
||||
- `salary:$1,500.50`
|
||||
|
||||
Você deseja mascarar automaticamente esses valores para proteger dados sensíveis de remuneração.
|
||||
|
||||
### Configuração
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Name** | `SALARY` |
|
||||
| **Entity Type** | `SALARY` |
|
||||
| **Type** | Regex Pattern |
|
||||
| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` |
|
||||
| **Action** | Mask |
|
||||
| **Confidence Threshold** | `0.8` |
|
||||
| **Context Words** | `salary, compensation, pay, wage, income` |
|
||||
|
||||
### Análise do Padrão Regex
|
||||
|
||||
| Componente do Padrão | Significado |
|
||||
|----------------------|-------------|
|
||||
| `salary:` | Corresponde ao texto literal "salary:" |
|
||||
| `\s*` | Corresponde a zero ou mais caracteres de espaço em branco |
|
||||
| `\$` | Corresponde ao sinal de dólar (escapado) |
|
||||
| `\s*` | Corresponde a zero ou mais caracteres de espaço em branco após $ |
|
||||
| `\d{1,3}` | Corresponde a 1-3 dígitos (ex.: "1", "50", "125") |
|
||||
| `(,\d{3})*` | Corresponde a milhares separados por vírgula (ex.: ",000", ",500,000") |
|
||||
| `(\.\d{2})?` | Opcionalmente corresponde a centavos (ex.: ".00", ".50") |
|
||||
|
||||
### Resultados de Exemplo
|
||||
|
||||
```
|
||||
Original: "Registro do funcionário mostra salary: $125,000.00 anualmente"
|
||||
Redigido: "Registro do funcionário mostra <SALARY> anualmente"
|
||||
|
||||
Original: "Salário base salary:$50,000 com potencial de bônus"
|
||||
Redigido: "Salário base <SALARY> com potencial de bônus"
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Adicionar palavras de contexto como "salary", "compensation", "pay", "wage" e "income" ajuda a aumentar a confiança de detecção quando esses termos aparecem próximos ao padrão correspondido, reduzindo falsos positivos.
|
||||
</Tip>
|
||||
|
||||
### Habilite o Reconhecedor para Suas Implantações
|
||||
|
||||
<Warning>
|
||||
Criar um reconhecedor personalizado no nível da organização não o habilita automaticamente para suas implantações. Você deve habilitar manualmente cada reconhecedor para cada implantação onde deseja aplicá-lo.
|
||||
</Warning>
|
||||
|
||||
Após criar seu reconhecedor personalizado, habilite-o para cada implantação:
|
||||
|
||||
<Steps>
|
||||
<Step title="Navegue até Sua Implantação">
|
||||
Vá para sua implantação/automação e abra **Settings** → **PII Protection**.
|
||||
</Step>
|
||||
|
||||
<Step title="Selecione Reconhecedores Personalizados">
|
||||
Em **Mask Recognizers**, você verá os reconhecedores definidos pela sua organização. Marque a caixa ao lado dos reconhecedores que deseja habilitar.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="Salvar Configuração">
|
||||
Salve suas alterações. O reconhecedor estará ativo em todas as execuções subsequentes para esta implantação.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Info>
|
||||
Repita este processo para cada implantação onde você precisa do reconhecedor personalizado. Isso oferece controle granular sobre quais reconhecedores estão ativos em diferentes ambientes (ex.: desenvolvimento vs. produção).
|
||||
</Info>
|
||||
255
docs/edge/pt-BR/enterprise/features/rbac.mdx
Normal file
255
docs/edge/pt-BR/enterprise/features/rbac.mdx
Normal file
@@ -0,0 +1,255 @@
|
||||
---
|
||||
title: "Controle de Acesso Baseado em Funções (RBAC)"
|
||||
description: "Controle o acesso a crews, ferramentas e dados com funções, escopos e permissões granulares."
|
||||
icon: "shield"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O RBAC no CrewAI AMP permite gerenciamento de acesso seguro e escalável através de duas camadas:
|
||||
|
||||
1. **Permissões de funcionalidade** — controlam o que cada função pode fazer na plataforma (gerenciar, ler ou sem acesso)
|
||||
2. **Permissões em nível de entidade** — acesso granular em automações individuais, variáveis de ambiente, conexões LLM e repositórios Git
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/users_and_roles.png" alt="Visão geral de RBAC no CrewAI AMP" />
|
||||
</Frame>
|
||||
|
||||
## Usuários e Funções
|
||||
|
||||
Cada membro da sua workspace CrewAI recebe uma função, que determina seu acesso aos diversos recursos.
|
||||
|
||||
Você pode:
|
||||
|
||||
- Usar funções pré-definidas (Owner, Member)
|
||||
- Criar funções personalizadas com permissões específicas
|
||||
- Atribuir funções a qualquer momento no painel de configurações
|
||||
|
||||
A configuração de usuários e funções é feita em Settings → Roles.
|
||||
|
||||
<Steps>
|
||||
<Step title="Abrir Roles">
|
||||
Vá em <b>Settings → Roles</b> no CrewAI AMP.
|
||||
</Step>
|
||||
<Step title="Escolher a função">
|
||||
Use uma função pré-definida (<b>Owner</b>, <b>Member</b>) ou clique em{" "}
|
||||
<b>Create role</b> para criar uma personalizada.
|
||||
</Step>
|
||||
<Step title="Atribuir aos membros">
|
||||
Selecione os usuários e atribua a função. Você pode alterar depois.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Funções Pré-definidas
|
||||
|
||||
| Função | Descrição |
|
||||
| :--------- | :------------------------------------------------------------------------ |
|
||||
| **Owner** | Acesso total a todas as funcionalidades e configurações. Não pode ser restrito. |
|
||||
| **Member** | Acesso de leitura à maioria das funcionalidades, acesso de gerenciamento a variáveis de ambiente, conexões LLM e projetos Studio. Não pode modificar configurações da organização ou padrões. |
|
||||
|
||||
### Resumo de configuração
|
||||
|
||||
| Área | Onde configurar | Opções |
|
||||
| :------------------------ | :--------------------------------- | :--------------------------------------------------- |
|
||||
| Usuários & Funções | Settings → Roles | Pré-definidas: Owner, Member; Funções personalizadas |
|
||||
| Visibilidade da automação | Automation → Settings → Visibility | Private; Lista de usuários/funções |
|
||||
|
||||
---
|
||||
|
||||
## Matriz de Permissões de Funcionalidades
|
||||
|
||||
Cada função possui um nível de permissão para cada área de funcionalidade. Os três níveis são:
|
||||
|
||||
- **Manage** — acesso total de leitura/escrita (criar, editar, excluir)
|
||||
- **Read** — acesso somente leitura
|
||||
- **No access** — funcionalidade oculta/inacessível
|
||||
|
||||
| Funcionalidade | Owner | Member (padrão) | Níveis disponíveis | Descrição |
|
||||
| :------------------------ | :------ | :--------------- | :------------------------ | :-------------------------------------------------------------- |
|
||||
| `usage_dashboards` | Manage | Read | Manage / Read / No access | Visualizar métricas e análises de uso |
|
||||
| `crews_dashboards` | Manage | Read | Manage / Read / No access | Visualizar dashboards de deploy, acessar detalhes de automações |
|
||||
| `invitations` | Manage | Read | Manage / Read / No access | Convidar novos membros para a organização |
|
||||
| `training_ui` | Manage | Read | Manage / Read / No access | Acessar interfaces de treinamento/fine-tuning |
|
||||
| `tools` | Manage | Read | Manage / Read / No access | Criar e gerenciar ferramentas |
|
||||
| `agents` | Manage | Read | Manage / Read / No access | Criar e gerenciar agentes |
|
||||
| `environment_variables` | Manage | Manage | Manage / No access | Criar e gerenciar variáveis de ambiente |
|
||||
| `llm_connections` | Manage | Manage | Manage / No access | Configurar conexões de provedores LLM |
|
||||
| `default_settings` | Manage | No access | Manage / No access | Modificar configurações padrão da organização |
|
||||
| `organization_settings` | Manage | No access | Manage / No access | Gerenciar cobrança, planos e configuração da organização |
|
||||
| `studio_projects` | Manage | Manage | Manage / No access | Criar e editar projetos no Studio |
|
||||
|
||||
<Tip>
|
||||
Ao criar uma função personalizada, a maioria das funcionalidades pode ser definida como **Manage**, **Read** ou **No access**. No entanto, `environment_variables`, `llm_connections`, `default_settings`, `organization_settings` e `studio_projects` suportam apenas **Manage** ou **No access** — não há opção somente leitura para essas funcionalidades.
|
||||
</Tip>
|
||||
|
||||
---
|
||||
|
||||
## Deploy via GitHub ou Zip
|
||||
|
||||
Uma das perguntas mais comuns sobre RBAC é: _"Quais permissões um membro da equipe precisa para fazer deploy?"_
|
||||
|
||||
### Deploy via GitHub
|
||||
|
||||
Para fazer deploy de uma automação a partir de um repositório GitHub, o usuário precisa de:
|
||||
|
||||
1. **`crews_dashboards`**: pelo menos `Read` — necessário para acessar o dashboard de automações onde os deploys são criados
|
||||
2. **Acesso ao repositório Git** (se RBAC em nível de entidade para repositórios Git estiver habilitado): a função do usuário deve ter acesso ao repositório Git específico via permissões de entidade
|
||||
3. **`studio_projects`: `Manage`** — se estiver construindo o crew no Studio antes do deploy
|
||||
|
||||
### Deploy via Zip
|
||||
|
||||
Para fazer deploy de uma automação via upload de arquivo Zip, o usuário precisa de:
|
||||
|
||||
1. **`crews_dashboards`**: pelo menos `Read` — necessário para acessar o dashboard de automações
|
||||
2. **Deploys via Zip habilitados**: a organização não deve ter desabilitado deploys via Zip nas configurações da organização
|
||||
|
||||
### Referência Rápida: Permissões Mínimas para Deploy
|
||||
|
||||
| Ação | Permissões de funcionalidade necessárias | Requisitos adicionais |
|
||||
| :------------------------- | :--------------------------------------- | :------------------------------------------------ |
|
||||
| Deploy via GitHub | `crews_dashboards: Read` | Acesso à entidade do repositório Git (se habilitado) |
|
||||
| Deploy via Zip | `crews_dashboards: Read` | Deploys via Zip devem estar habilitados na organização |
|
||||
| Construir no Studio | `studio_projects: Manage` | — |
|
||||
| Configurar chaves LLM | `llm_connections: Manage` | — |
|
||||
| Definir variáveis de ambiente | `environment_variables: Manage` | Acesso em nível de entidade (se habilitado) |
|
||||
|
||||
---
|
||||
|
||||
## Controle de Acesso em Nível de Automação (Permissões de Entidade)
|
||||
|
||||
Além das funções em nível de organização, o CrewAI suporta permissões granulares em nível de entidade que restringem o acesso a recursos individuais.
|
||||
|
||||
### Visibilidade da Automação
|
||||
|
||||
Automações suportam configurações de visibilidade que restringem acesso por usuário ou função. Útil para:
|
||||
|
||||
- Manter automações sensíveis ou experimentais privadas
|
||||
- Gerenciar visibilidade em equipes grandes ou colaboradores externos
|
||||
- Testar automações em contexto isolado
|
||||
|
||||
Deploys podem ser configurados como privados, significando que apenas usuários e funções na whitelist poderão interagir com eles.
|
||||
|
||||
Configure em Automation → Settings → aba Visibility.
|
||||
|
||||
<Steps>
|
||||
<Step title="Abrir a aba Visibility">
|
||||
Acesse <b>Automation → Settings → Visibility</b>.
|
||||
</Step>
|
||||
<Step title="Definir visibilidade">
|
||||
Selecione <b>Private</b> para restringir o acesso. O owner da organização
|
||||
mantém acesso sempre.
|
||||
</Step>
|
||||
<Step title="Permitir acesso">
|
||||
Adicione usuários e funções que poderão ver, executar e acessar
|
||||
logs/métricas/configurações.
|
||||
</Step>
|
||||
<Step title="Salvar e verificar">
|
||||
Salve e confirme que não listados não conseguem ver ou executar a automação.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Resultado de acesso no modo Private
|
||||
|
||||
| Ação | Owner | Usuário/função na whitelist | Não listado |
|
||||
| :-------------------------- | :---- | :-------------------------- | :---------- |
|
||||
| Ver automação | ✓ | ✓ | ✗ |
|
||||
| Executar/API | ✓ | ✓ | ✗ |
|
||||
| Logs/métricas/configurações | ✓ | ✓ | ✗ |
|
||||
|
||||
<Tip>
|
||||
O owner sempre possui acesso. Em modo privado, somente usuários/funções na
|
||||
whitelist têm permissão.
|
||||
</Tip>
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/visibility.png" alt="Configuração de visibilidade no CrewAI AMP" />
|
||||
</Frame>
|
||||
|
||||
### Tipos de Permissão de Deploy
|
||||
|
||||
Ao conceder acesso em nível de entidade a uma automação específica, você pode atribuir estes tipos de permissão:
|
||||
|
||||
| Permissão | O que permite |
|
||||
| :------------------- | :-------------------------------------------------- |
|
||||
| `run` | Executar a automação e usar sua API |
|
||||
| `traces` | Visualizar traces de execução e logs |
|
||||
| `manage_settings` | Editar, reimplantar, reverter ou excluir a automação |
|
||||
| `human_in_the_loop` | Responder a solicitações human-in-the-loop (HITL) |
|
||||
| `full_access` | Todos os anteriores |
|
||||
|
||||
### RBAC em Nível de Entidade para Outros Recursos
|
||||
|
||||
Quando o RBAC em nível de entidade está habilitado, o acesso a estes recursos também pode ser controlado por usuário ou função:
|
||||
|
||||
| Recurso | Controlado por | Descrição |
|
||||
| :--------------------- | :------------------------------------- | :------------------------------------------------------------- |
|
||||
| Variáveis de ambiente | Flag de funcionalidade RBAC de entidade | Restringir quais funções/usuários podem ver ou gerenciar variáveis específicas |
|
||||
| Conexões LLM | Flag de funcionalidade RBAC de entidade | Restringir acesso a configurações de provedores LLM específicos |
|
||||
| Repositórios Git | Configuração RBAC de repositórios Git | Restringir quais funções/usuários podem acessar repositórios conectados específicos |
|
||||
|
||||
---
|
||||
|
||||
## Padrões Comuns de Funções
|
||||
|
||||
Embora o CrewAI venha com as funções Owner e Member, a maioria das equipes se beneficia da criação de funções personalizadas. Aqui estão os padrões comuns:
|
||||
|
||||
### Função Developer
|
||||
|
||||
Uma função para membros da equipe que constroem e fazem deploy de automações, mas não gerenciam configurações da organização.
|
||||
|
||||
| Funcionalidade | Permissão |
|
||||
| :------------------------ | :--------- |
|
||||
| `usage_dashboards` | Read |
|
||||
| `crews_dashboards` | Manage |
|
||||
| `invitations` | Read |
|
||||
| `training_ui` | Read |
|
||||
| `tools` | Manage |
|
||||
| `agents` | Manage |
|
||||
| `environment_variables` | Manage |
|
||||
| `llm_connections` | Manage |
|
||||
| `default_settings` | No access |
|
||||
| `organization_settings` | No access |
|
||||
| `studio_projects` | Manage |
|
||||
|
||||
### Função Viewer / Stakeholder
|
||||
|
||||
Uma função para stakeholders não técnicos que precisam monitorar automações e visualizar resultados.
|
||||
|
||||
| Funcionalidade | Permissão |
|
||||
| :------------------------ | :--------- |
|
||||
| `usage_dashboards` | Read |
|
||||
| `crews_dashboards` | Read |
|
||||
| `invitations` | No access |
|
||||
| `training_ui` | Read |
|
||||
| `tools` | Read |
|
||||
| `agents` | Read |
|
||||
| `environment_variables` | No access |
|
||||
| `llm_connections` | No access |
|
||||
| `default_settings` | No access |
|
||||
| `organization_settings` | No access |
|
||||
| `studio_projects` | No access |
|
||||
|
||||
### Função Ops / Platform Admin
|
||||
|
||||
Uma função para operadores de plataforma que gerenciam configurações de infraestrutura, mas podem não construir agentes.
|
||||
|
||||
| Funcionalidade | Permissão |
|
||||
| :------------------------ | :--------- |
|
||||
| `usage_dashboards` | Manage |
|
||||
| `crews_dashboards` | Manage |
|
||||
| `invitations` | Manage |
|
||||
| `training_ui` | Read |
|
||||
| `tools` | Read |
|
||||
| `agents` | Read |
|
||||
| `environment_variables` | Manage |
|
||||
| `llm_connections` | Manage |
|
||||
| `default_settings` | Manage |
|
||||
| `organization_settings` | Read |
|
||||
| `studio_projects` | No access |
|
||||
|
||||
---
|
||||
|
||||
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
|
||||
Fale com o nosso time para suporte em configuração de RBAC.
|
||||
</Card>
|
||||
@@ -0,0 +1,321 @@
|
||||
---
|
||||
title: AWS Workload Identity (Federação OIDC)
|
||||
description: Configure o AWS Secrets Manager via Workload Identity para acesso a segredos consciente de rotação e sem credenciais
|
||||
sidebarTitle: Com Workload Identity
|
||||
icon: "id-badge"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Este guia configura o AWS Secrets Manager como provedor de segredos usando **Workload Identity Federation**: a CrewAI Platform emite tokens OIDC de curta duração, os troca por credenciais AWS via STS e lê seus segredos — sem que uma chave de acesso AWS de longa duração seja armazenada em lugar algum.
|
||||
|
||||
<Note>
|
||||
**Por que este caminho:** os segredos são resolvidos no momento de execução da automação, então **valores rotacionados se propagam para o próximo kickoff sem novo deploy**. Se você só precisa de credenciais estáticas e não se importa com a propagação de rotação, veja o guia mais simples [AWS — chaves estáticas / AssumeRole](/pt-BR/enterprise/features/secrets-manager/aws).
|
||||
</Note>
|
||||
|
||||
### Como funciona em runtime
|
||||
|
||||
1. O worker do deployment solicita um JWT OIDC fresco à CrewAI Platform.
|
||||
2. O worker chama `sts:AssumeRoleWithWebIdentity` no role IAM que você configurou abaixo, apresentando o JWT.
|
||||
3. O AWS STS valida o JWT contra o issuer OIDC público da CrewAI Platform (então sua instalação da plataforma deve ser acessível a partir da AWS), depois retorna credenciais AWS de curta duração.
|
||||
4. O worker usa essas credenciais para chamar `secretsmanager:GetSecretValue`.
|
||||
5. O valor obtido é injetado como valor da variável de ambiente para aquele kickoff de automação.
|
||||
|
||||
Tokens OIDC subject são cacheados por ~1 hora para evitar reemissão a cada kickoff. Valores de segredos são buscados frescos a cada kickoff independentemente do estado do cache OIDC, e é isso que torna este caminho consciente de rotação.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
<Note>
|
||||
Antes de começar, certifique-se de que você tem:
|
||||
|
||||
- A imagem do pod de automação deve incluir o runtime da CrewAI versão `1.14.5` ou superior.
|
||||
- Uma conta AWS com permissão para criar provedores IAM OIDC, roles IAM e políticas IAM.
|
||||
- A região AWS onde seus segredos vivem (ou viverão), ex. `us-east-1`.
|
||||
- Uma organização na CrewAI Platform onde seu usuário tem as permissões `workload_identity_configs: manage` e `secret_providers: manage`. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac).
|
||||
- **O UUID da sua organização CrewAI.** Encontre-o na página de configurações da organização na CrewAI Platform — a trust policy no Passo 3 vincula o role IAM a esta organização específica.
|
||||
- **Sua instalação da CrewAI Platform deve ser acessível a partir da AWS via HTTPS** para que o AWS STS possa buscar o documento de discovery OIDC e o JWKS durante a validação do token. Confirme com o administrador da sua plataforma que o host é acessível pela internet (ou que a AWS tem alcance de rede até ele via VPC peering / equivalente).
|
||||
</Note>
|
||||
|
||||
## Passo 1 — Encontre a URL do Issuer OIDC da Sua CrewAI Platform
|
||||
|
||||
Sua instalação da CrewAI Platform publica um documento de discovery OpenID Connect em `https://<your-platform-host>/.well-known/openid-configuration`. O campo `issuer` nesse documento é a URL que a AWS registrará como provedor OIDC confiável.
|
||||
|
||||
Abra a URL em um navegador (substituindo `<your-platform-host>` pelo seu hostname real, ex. `app.crewai.com`):
|
||||
|
||||
```
|
||||
https://<your-platform-host>/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
Você deverá ver um JSON contendo:
|
||||
|
||||
```json
|
||||
{
|
||||
"issuer": "https://<your-platform-host>",
|
||||
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Anote o valor exato de `issuer` — você o usará no Passo 3.
|
||||
|
||||
<Tip>
|
||||
Se a URL retornar 404 ou 503, contate o administrador da sua plataforma. O issuer OIDC requer uma chave de assinatura privada configurada no momento da instalação. Veja o guia de instalação da plataforma para as configurações `OIDC_PRIVATE_KEY` e `OIDC_ISSUER`.
|
||||
</Tip>
|
||||
|
||||
## Passo 2 — Registrar a CrewAI Platform como um IAM OIDC Identity Provider
|
||||
|
||||
Abra o [console IAM → Identity providers](https://console.aws.amazon.com/iam/home#/identity_providers) e clique em **Add provider**.
|
||||
|
||||
- **Provider type:** OpenID Connect.
|
||||
- **Provider URL:** o valor de `issuer` do Passo 1 (ex. `https://app.crewai.com`).
|
||||
- **Audience:** `sts.amazonaws.com`
|
||||
|
||||
Clique em **Add provider**.
|
||||
|
||||
Ou via CLI:
|
||||
|
||||
```bash
|
||||
aws iam create-open-id-connect-provider \
|
||||
--url "https://<your-platform-host>" \
|
||||
--client-id-list "sts.amazonaws.com" \
|
||||
--thumbprint-list "$(echo | openssl s_client -servername <your-platform-host> -connect <your-platform-host>:443 2>/dev/null | openssl x509 -fingerprint -noout -sha1 | cut -d= -f2 | tr -d ':')"
|
||||
```
|
||||
|
||||
Copie o **OpenIDConnectProviderArn** da saída (ou o ARN do provedor no console). Você o usará no Passo 3.
|
||||
|
||||
<Note>
|
||||
A AWS não valida de fato o thumbprint para chamadas STS WebIdentity — ela sempre re-busca o JWKS no momento da validação — mas a API requer que o campo esteja presente.
|
||||
</Note>
|
||||
|
||||
{/* SCREENSHOT: AWS IAM "Add identity provider" form filled with the Platform issuer URL and audience sts.amazonaws.com → /images/secrets-manager/aws-wi/01-add-oidc-provider.png */}
|
||||
{/* SCREENSHOT: Provider detail page showing the provider's ARN → /images/secrets-manager/aws-wi/02-oidc-provider-arn.png */}
|
||||
|
||||
## Passo 3 — Criar o Role IAM
|
||||
|
||||
Salve como `trust-policy.json`, substituindo `<YOUR_ACCOUNT_ID>`, `<your-platform-host>` (o host do issuer **sem** `https://` ou `http://`, ex. `app.crewai.com`) e `<YOUR_CREWAI_ORG_UUID>` (dos Pré-requisitos):
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Principal": {
|
||||
"Federated": "arn:aws:iam::<YOUR_ACCOUNT_ID>:oidc-provider/<your-platform-host>"
|
||||
},
|
||||
"Action": "sts:AssumeRoleWithWebIdentity",
|
||||
"Condition": {
|
||||
"StringEquals": {
|
||||
"<your-platform-host>:aud": "sts.amazonaws.com",
|
||||
"<your-platform-host>:sub": "organization:<YOUR_CREWAI_ORG_UUID>"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Crie o role:
|
||||
|
||||
```bash
|
||||
aws iam create-role \
|
||||
--role-name crewai-secrets-reader \
|
||||
--assume-role-policy-document file://trust-policy.json
|
||||
```
|
||||
|
||||
Copie o **Role Arn** da saída — esse é seu `aws_role_arn`. Você o colará na CrewAI Platform no Passo 6.
|
||||
|
||||
<Tip>
|
||||
As duas condições escopam a confiança com precisão: `aud` restringe a assunção a tokens com a audience do AWS STS, e `sub` escopa a federação a uma organização CrewAI específica — apenas tokens emitidos para as automações dessa org são aceitos. A CrewAI Platform sempre define ambas as claims nos tokens de workload identity da AWS.
|
||||
</Tip>
|
||||
|
||||
{/* SCREENSHOT: IAM "Create role" with Web Identity trust type, federated provider selector pointing at the CrewAI Platform OIDC provider → /images/secrets-manager/aws-wi/03-create-role-trust.png */}
|
||||
|
||||
## Passo 4 — Criar e anexar a política IAM para acesso ao Secrets Manager + KMS
|
||||
|
||||
Salve como `secrets-policy.json`, substituindo os placeholders pelo ID da sua conta, região, prefixo do nome do segredo e o(s) ARN(s) da chave KMS que criptografa(m) esses segredos:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "SecretsManagerListForUI",
|
||||
"Effect": "Allow",
|
||||
"Action": "secretsmanager:ListSecrets",
|
||||
"Resource": "*"
|
||||
},
|
||||
{
|
||||
"Sid": "SecretsManagerRead",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"secretsmanager:GetSecretValue"
|
||||
],
|
||||
"Resource": "arn:aws:secretsmanager:<REGION>:<YOUR_ACCOUNT_ID>:secret:<SECRET_NAME_PREFIX>-*"
|
||||
},
|
||||
{
|
||||
"Sid": "KMSDecrypt",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"kms:Decrypt"
|
||||
],
|
||||
"Resource": "arn:aws:kms:<REGION>:<YOUR_ACCOUNT_ID>:key/<KMS_KEY_ID>"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`SecretsManagerListForUI` alimenta o **autocomplete de Secret Name** no formulário de Environment Variables e o botão **Test Connection** na credencial. `secretsmanager:ListSecrets` só aceita `Resource: "*"` — é escopado por conta na camada IAM.
|
||||
|
||||
Anexe a política ao role usando a CLI (política inline, mais simples) ou a UI do console; para ambientes que reutilizam as mesmas permissões em vários roles, use a aba **Managed policy** para uma política nomeada e reutilizável.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Política inline (CLI)">
|
||||
```bash
|
||||
aws iam put-role-policy \
|
||||
--role-name crewai-secrets-reader \
|
||||
--policy-name SecretsManagerRead \
|
||||
--policy-document file://secrets-policy.json
|
||||
```
|
||||
|
||||
Isso anexa a política **inline** ao role. Políticas inline são vinculadas ao role e não podem ser reutilizadas em outros roles.
|
||||
</Tab>
|
||||
|
||||
<Tab title="Política gerenciada (CLI, reutilizável)">
|
||||
```bash
|
||||
POLICY_ARN=$(aws iam create-policy \
|
||||
--policy-name CrewAISecretsReader \
|
||||
--policy-document file://secrets-policy.json \
|
||||
--query 'Policy.Arn' --output text)
|
||||
|
||||
aws iam attach-role-policy \
|
||||
--role-name crewai-secrets-reader \
|
||||
--policy-arn "$POLICY_ARN"
|
||||
```
|
||||
|
||||
Uma política gerenciada é um recurso IAM autônomo que você pode anexar a vários roles.
|
||||
</Tab>
|
||||
|
||||
<Tab title="Console (UI)">
|
||||
1. Abra o [console IAM → Roles](https://console.aws.amazon.com/iam/home#/roles) e selecione **crewai-secrets-reader**.
|
||||
2. Na aba **Permissions**, clique em **Add permissions** → **Create inline policy**.
|
||||
3. Mude para o editor **JSON** e cole o conteúdo de `secrets-policy.json`.
|
||||
4. Clique em **Next**, dê um nome à política (ex. `SecretsManagerRead`) e clique em **Create policy**.
|
||||
|
||||
Para criar uma política gerenciada reutilizável, use **IAM → Policies → Create policy** e depois anexe-a ao role pela aba **Permissions** do role.
|
||||
|
||||
{/* SCREENSHOT: IAM Role detail → Permissions → Create inline policy with JSON editor → /images/secrets-manager/aws-wi/03b-attach-inline-policy.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Passo 5 — Criar Pelo Menos Um Segredo na AWS
|
||||
|
||||
Se você ainda não tem um segredo para testar, crie um agora:
|
||||
|
||||
```bash
|
||||
aws secretsmanager create-secret \
|
||||
--region <REGION> \
|
||||
--name crewai-test-keyword \
|
||||
--secret-string "hello from aws"
|
||||
```
|
||||
|
||||
Ou pelo [console do AWS Secrets Manager](https://console.aws.amazon.com/secretsmanager/) → **Store a new secret**.
|
||||
|
||||
{/* SCREENSHOT: AWS Secrets Manager "Store a new secret" page with a sample value → /images/secrets-manager/aws-wi/04-create-secret.png */}
|
||||
|
||||
## Passo 6 — Adicionar uma Configuração de Workload Identity na CrewAI Platform
|
||||
|
||||
Na CrewAI Platform, navegue até **Settings** → **Workload Identity** e clique em **Add Workload Identity Config**.
|
||||
|
||||
{/* SCREENSHOT: Sidebar highlighting Settings → Workload Identity → /images/secrets-manager/aws-wi/05-amp-settings-wi-nav.png */}
|
||||
{/* SCREENSHOT: Empty state of Workload Identity page with "Add Workload Identity Config" button → /images/secrets-manager/aws-wi/06-amp-wi-empty-state.png */}
|
||||
|
||||
Preencha o formulário:
|
||||
|
||||
- **Name:** Um nome descritivo, ex. `aws-prod`.
|
||||
- **Cloud Provider:** `AWS`.
|
||||
- **AWS Role ARN:** o **Role Arn** do Passo 3.
|
||||
- **AWS Region:** a região onde seus segredos vivem, ex. `us-east-1`.
|
||||
- (Opcional) Marque **Set as default for AWS** se você quiser que esta config WI seja a padrão selecionada ao criar uma credencial de segredo baseada em AWS.
|
||||
|
||||
Clique em **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Workload Identity Config" form with AWS, role ARN, and region filled in → /images/secrets-manager/aws-wi/07-amp-add-wi-config-aws.png */}
|
||||
{/* SCREENSHOT: Workload Identity list showing the new AWS row with "(default)" badge if applicable → /images/secrets-manager/aws-wi/08-amp-wi-list-with-aws.png */}
|
||||
|
||||
## Passo 7 — Adicionar uma Credencial de Provedor de Segredos Vinculada à Config WI
|
||||
|
||||
Navegue até **Settings** → **Secret Provider Credentials** e clique em **Add Credential**.
|
||||
|
||||
Preencha o formulário:
|
||||
|
||||
- **Name:** Um nome descritivo, ex. `aws-prod-wi`.
|
||||
- **Provider:** `AWS Secrets Manager`.
|
||||
- **Authentication Method:** `Workload Identity` (em vez de chaves estáticas / AssumeRole).
|
||||
- **Workload Identity Configuration:** selecione a config que você criou no Passo 6 (ex. `aws-prod`).
|
||||
- (Opcional) Marque **Set as default credential for this provider**.
|
||||
|
||||
O formulário pedirá apenas a **AWS Region** sob Workload Identity — os campos de credencial estática (Access Key ID, Secret Access Key, Role ARN, External ID) estão intencionalmente ocultos porque não se aplicam a este caminho; o ARN do role vem da config WI vinculada.
|
||||
|
||||
Clique em **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + Workload Identity + WI config dropdown selected → /images/secrets-manager/aws-wi/09-amp-add-credential-aws-wi.png */}
|
||||
|
||||
## Passo 8 — Testar a Conexão
|
||||
|
||||
Depois de salvar a credencial, clique em **Test Connection**. Para credenciais workload-identity isso verifica o handshake OIDC: a CrewAI Platform emite um JWT, troca-o com o AWS STS via `sts:AssumeRoleWithWebIdentity` e confirma que as credenciais resultantes podem chamar `sts:GetCallerIdentity` contra o role assumido. Um resultado verde significa que o vínculo de federação está saudável.
|
||||
|
||||
Um Test Connection bem-sucedido prova que a trust policy, o registro do provedor OIDC e a condição de audience estão todos conectados corretamente. Ele **não** prova que o IAM por segredo está correto — `secretsmanager:GetSecretValue` em um ARN de segredo específico é exercitado separadamente quando uma variável de ambiente é resolvida no kickoff. Veja [Solução de Problemas](#troubleshooting) para modos de falha de handshake.
|
||||
|
||||
## Passo 9 — Referenciar o Segredo em uma Variável de Ambiente
|
||||
|
||||
Agora referencie o segredo em uma automação, exatamente como você faria para qualquer outra env var apoiada pelo Secrets Manager. Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) para os campos do formulário e o comportamento.
|
||||
|
||||
A única diferença entre env vars apoiadas por WI e por chaves estáticas é **quando** o segredo é lido:
|
||||
|
||||
- **Apoiado por WI:** o valor do segredo é lido de forma fresca a cada kickoff de automação.
|
||||
- **Apoiado por chaves estáticas:** o valor do segredo é lido no momento do deploy e incorporado à imagem do deployment.
|
||||
|
||||
## Passo 10 — Verificar a Rotação
|
||||
|
||||
Após o deployment estar rodando, rotacione o segredo na AWS:
|
||||
|
||||
```bash
|
||||
aws secretsmanager update-secret \
|
||||
--region <REGION> \
|
||||
--secret-id crewai-test-keyword \
|
||||
--secret-string "rotated value"
|
||||
```
|
||||
|
||||
Dispare um novo kickoff de automação. O ambiente do kickoff verá `"rotated value"` — sem novo deploy, sem reinício de worker, sem esperar TTL.
|
||||
|
||||
Para confirmar nos logs (se você tiver acesso ao worker), procure por:
|
||||
|
||||
```
|
||||
Workload identity config '<id>' (aws): N secret(s) resolved
|
||||
```
|
||||
|
||||
Esta linha aparece para cada kickoff e indica uma chamada `GetSecretValue` fresca contra a AWS.
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
| Sintoma | Causa provável |
|
||||
|---|---|
|
||||
| Test Connection falha com erro de handshake | A chamada `sts:AssumeRoleWithWebIdentity` foi rejeitada. Verifique se o ARN do principal federado da trust policy referencia `oidc-provider/<your-platform-host>` (host **sem** `https://` ou `http://`, sem barra final), se a condição de audience é exatamente `sts.amazonaws.com`, se a condição `sub` corresponde ao UUID da sua organização CrewAI e se a URL de discovery OIDC da plataforma é acessível a partir da AWS pela internet pública. |
|
||||
| `InvalidIdentityToken: Couldn't retrieve verification key from your identity provider` | O AWS STS não consegue acessar o host da sua CrewAI Platform para buscar o JWKS. Confirme que o host é acessível pela internet a partir da AWS, que a URL de discovery OIDC retorna 200 e que o endpoint JWKS é acessível. |
|
||||
| `AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity` | Trust policy incompatível. Reconfira o Passo 3: o ARN do principal federado deve incluir `oidc-provider/<your-platform-host>` (host **sem** `https://` ou `http://`, sem barra final), a condição de audience deve ser exatamente `sts.amazonaws.com` e a condição `sub` deve ser igual a `organization:<YOUR_CREWAI_ORG_UUID>`. |
|
||||
| Autocomplete de Secret Name mostra `AccessDenied: secretsmanager:ListSecrets` | O role está sem `secretsmanager:ListSecrets` com `Resource: "*"`. Adicione a declaração `SecretsManagerListForUI` do Passo 4. |
|
||||
| Kickoff falha ao resolver um segredo mesmo que o Test Connection passe | O vínculo WI está saudável, mas o IAM escopado por recurso está ausente no segredo que falha. Audite as permissões `secretsmanager:GetSecretValue` e `kms:Decrypt` do role para o ARN específico desse segredo e chave KMS. |
|
||||
| `RegionDisabledException` / nenhum segredo encontrado | A região na Workload Identity Config não corresponde a onde o segredo vive. Reconfira o Passo 6. |
|
||||
| Valor rotacionado não é pego no próximo kickoff | Confirme que a env var na automação está referenciando uma credencial baseada em Workload Identity (não uma credencial de chaves estáticas). O caminho estático incorpora valores à imagem do deploy. |
|
||||
|
||||
### Links de Referência
|
||||
|
||||
- AWS: [Creating OpenID Connect (OIDC) identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)
|
||||
- AWS: [Configuring a role for OpenID Connect federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_relying-party.html)
|
||||
- AWS: [STS:AssumeRoleWithWebIdentity API reference](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
- [Use segredos em variáveis de ambiente e gerencie permissões](/pt-BR/enterprise/features/secrets-manager/usage)
|
||||
- Para multi-cloud, veja também [GCP Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity) e [Azure Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity).
|
||||
295
docs/edge/pt-BR/enterprise/features/secrets-manager/aws.mdx
Normal file
295
docs/edge/pt-BR/enterprise/features/secrets-manager/aws.mdx
Normal file
@@ -0,0 +1,295 @@
|
||||
---
|
||||
title: AWS Secrets Manager (Credenciais Estáticas)
|
||||
description: Configure o AWS Secrets Manager como provedor de segredos para a CrewAI Platform usando chaves de acesso estáticas ou AssumeRole
|
||||
sidebarTitle: Com Credenciais Estáticas
|
||||
icon: "key"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Este guia o orienta na configuração do AWS Secrets Manager como provedor de segredos para sua organização na CrewAI Platform, usando **credenciais estáticas** (chaves de acesso, opcionalmente com AssumeRole). Ao final, a CrewAI Platform poderá ler segredos armazenados na sua conta AWS e injetá-los como valores de variáveis de ambiente em runtime.
|
||||
|
||||
<Note>
|
||||
Este guia cobre o caminho de **credenciais estáticas** — segredos são resolvidos no momento do deploy e incorporados à imagem do deployment. Valores rotacionados exigem um novo deploy. Se você quiser segredos conscientes de rotação que se atualizam a cada kickoff de automação (sem novo deploy), veja [AWS Workload Identity (Federação OIDC)](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity).
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Este guia cobre a configuração do lado da AWS e a configuração da credencial na CrewAI Platform. Para então referenciar um segredo a partir de uma variável de ambiente, veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage).
|
||||
</Note>
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
<Note>
|
||||
Antes de começar, certifique-se de que você tem:
|
||||
|
||||
- Uma conta AWS com permissão para criar usuários IAM, políticas gerenciadas pelo cliente e (opcionalmente) papéis IAM.
|
||||
- A região AWS onde seus segredos vivem (ou viverão), por exemplo `us-east-1`.
|
||||
- Uma organização na CrewAI Platform onde seu usuário tem a permissão `secret_providers: manage`. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac).
|
||||
</Note>
|
||||
|
||||
## Escolha um Método de Autenticação
|
||||
|
||||
A CrewAI Platform suporta duas formas para que a plataforma se autentique no AWS Secrets Manager. Escolha uma antes de começar — os passos abaixo diferem dependendo do que você escolher.
|
||||
|
||||
| Método | Quando usar | Trade-offs |
|
||||
|---|---|---|
|
||||
| **Chaves de acesso estáticas** | Começar rápido, deployments single-account | Configuração mais simples; chaves de acesso devem ser rotacionadas manualmente |
|
||||
| **AssumeRole** | Cross-account, hardening de produção | Credenciais de curta duração; suporta External ID; requer papel IAM extra |
|
||||
|
||||
O restante deste guia usa abas nos Passos 3–5 para que você possa seguir o caminho que corresponde à sua escolha.
|
||||
|
||||
## Passo 1 — Criar um Usuário IAM
|
||||
|
||||
Abra o [console IAM](https://console.aws.amazon.com/iam/), navegue até **Users**, depois clique em **Create user**.
|
||||
|
||||
- Nome sugerido: `crewai-secrets-reader`.
|
||||
- Deixe **Provide user access to the AWS Management Console** desmarcado — este principal é usado programaticamente pela CrewAI Platform, não por humanos.
|
||||
- Clique em **Next**.
|
||||
|
||||
Na página **Set permissions**, deixe a seleção padrão. Você anexará a política no Passo 3.
|
||||
|
||||
Clique em **Next**, revise e clique em **Create user**.
|
||||
|
||||
Para detalhes completos, veja a documentação da AWS: [Create an IAM user in your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
|
||||
|
||||
{/* SCREENSHOT: AWS IAM "Create user" form filled with name "crewai-secrets-reader" → /images/secrets-manager/aws/01-create-iam-user.png */}
|
||||
|
||||
## Passo 2 — Criar a Política IAM
|
||||
|
||||
A CrewAI Platform precisa de acesso somente leitura ao AWS Secrets Manager e permissão para descriptografar segredos via KMS. Crie uma política gerenciada pelo cliente com o seguinte JSON.
|
||||
|
||||
No console IAM, navegue até **Policies**, depois clique em **Create policy**.
|
||||
|
||||
Escolha a aba **JSON** e substitua o conteúdo por:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "SecretsManagerRead",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"secretsmanager:ListSecrets",
|
||||
"secretsmanager:GetSecretValue",
|
||||
"secretsmanager:DescribeSecret"
|
||||
],
|
||||
"Resource": "*"
|
||||
},
|
||||
{
|
||||
"Sid": "KMSDecrypt",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"kms:DescribeKey",
|
||||
"kms:Decrypt"
|
||||
],
|
||||
"Resource": "*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Clique em **Next**, então na página **Review and create**:
|
||||
|
||||
- **Policy name:** `CrewAISecretsManagerRead`
|
||||
- **Description (optional):** `Read-only access to AWS Secrets Manager for CrewAI Platform`
|
||||
|
||||
Clique em **Create policy**.
|
||||
|
||||
<Tip>
|
||||
A política acima concede `*` em `Resource` para simplicidade. Em produção, restrinja o `Resource` aos ARNs dos segredos específicos que a CrewAI Platform deve acessar e restrinja `kms:Decrypt` aos ARNs das chaves KMS específicas que criptografam esses segredos. Veja a [orientação da AWS sobre menor privilégio](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html).
|
||||
</Tip>
|
||||
|
||||
{/* SCREENSHOT: AWS IAM "Create policy" → JSON tab with the policy above pasted → /images/secrets-manager/aws/02-create-policy-json-editor.png */}
|
||||
{/* SCREENSHOT: AWS IAM "Review and create policy" page with name "CrewAISecretsManagerRead" → /images/secrets-manager/aws/03-policy-review-and-create.png */}
|
||||
|
||||
## Passo 3 — Anexar a Política
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Chaves de acesso estáticas">
|
||||
1. No console IAM, navegue até **Users** e clique no usuário que você criou no Passo 1.
|
||||
2. Na aba **Permissions**, clique em **Add permissions** → **Attach policies directly**.
|
||||
3. Procure por `CrewAISecretsManagerRead`, selecione-a e clique em **Next**.
|
||||
4. Clique em **Add permissions**.
|
||||
|
||||
{/* SCREENSHOT: "Add permissions" → "Attach policies directly" with CrewAISecretsManagerRead selected → /images/secrets-manager/aws/04a-attach-policy-to-user.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="AssumeRole">
|
||||
Com AssumeRole, a política é anexada a um **role** IAM separado (não diretamente ao usuário). O usuário do Passo 1 só precisa de permissão para chamar `sts:AssumeRole` nesse role.
|
||||
|
||||
**Criar o role:**
|
||||
|
||||
1. No console IAM, navegue até **Roles** e clique em **Create role**.
|
||||
2. **Trusted entity type:** AWS account. Escolha **This account** (ou **Another AWS account** para setups cross-account, depois informe o ID da conta AWS que hospeda o usuário IAM do Passo 1).
|
||||
3. (Recomendado) Marque **Require external ID** e digite um valor que você mesmo gera — este é um segredo compartilhado que você colará na CrewAI Platform no Passo 5.
|
||||
4. Clique em **Next**.
|
||||
5. Anexe a política `CrewAISecretsManagerRead`.
|
||||
6. Clique em **Next**, nomeie o role como `CrewAISecretsManagerRole` e clique em **Create role**.
|
||||
|
||||
**Permitir que o usuário IAM assuma o role:**
|
||||
|
||||
1. Abra o role que você acabou de criar e copie seu **ARN**.
|
||||
2. No console IAM, navegue até **Users**, clique no usuário do Passo 1 e na aba **Permissions** clique em **Add permissions** → **Create inline policy**.
|
||||
3. Na aba **JSON**, cole o seguinte (substitua `ROLE_ARN_FROM_ABOVE`):
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Action": "sts:AssumeRole",
|
||||
"Resource": "ROLE_ARN_FROM_ABOVE"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
4. Nomeie a política como `CrewAIAssumeSecretsRole` e clique em **Create policy**.
|
||||
|
||||
{/* SCREENSHOT: IAM "Create role" trust policy step with External ID checkbox enabled → /images/secrets-manager/aws/04b-create-role-trust-policy.png */}
|
||||
{/* SCREENSHOT: Inline sts:AssumeRole policy attached to the IAM user → /images/secrets-manager/aws/04c-attach-assumerole-on-user.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Passo 4 — Obter Credenciais
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Chaves de acesso estáticas">
|
||||
1. No console IAM, abra o usuário do Passo 1.
|
||||
2. Clique na aba **Security credentials**.
|
||||
3. Em **Access keys**, clique em **Create access key**.
|
||||
4. Selecione **Application running outside AWS** (ou **Other**) como caso de uso. Clique em **Next**.
|
||||
5. (Opcional) Adicione uma tag de descrição. Clique em **Create access key**.
|
||||
6. Clique em **Show** para revelar a secret access key, então copie tanto o **Access key ID** quanto a **Secret access key**, ou clique em **Download .csv file**.
|
||||
|
||||
<Warning>
|
||||
A secret access key é mostrada apenas uma vez. Se você fechar esta página sem copiá-la, precisará excluir a chave e criar uma nova.
|
||||
</Warning>
|
||||
|
||||
Para detalhes completos, veja a documentação da AWS: [Manage access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
|
||||
|
||||
{/* SCREENSHOT: Access key use-case selector ("Application running outside AWS") → /images/secrets-manager/aws/05a-create-access-key-use-case.png */}
|
||||
{/* SCREENSHOT: "Retrieve access keys" page with Show/Download buttons → /images/secrets-manager/aws/06a-retrieve-access-keys.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="AssumeRole">
|
||||
Mesmo com AssumeRole, a CrewAI Platform ainda precisa de uma chave de acesso para o usuário IAM — ela usa essas chaves como identidade chamadora para realizar a chamada `sts:AssumeRole`.
|
||||
|
||||
1. Crie uma access key para o usuário exatamente como descrito na aba **Chaves de acesso estáticas** acima.
|
||||
2. Abra o role que você criou no Passo 3 e copie:
|
||||
- O **Role ARN** (do resumo do role).
|
||||
- O **External ID** que você configurou (se houver) — você definiu isso no Passo 3, então certifique-se de tê-lo à mão.
|
||||
|
||||
{/* SCREENSHOT: IAM role detail page showing Role ARN → /images/secrets-manager/aws/05b-role-arn-detail.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Passo 5 — Adicionar a Credencial na CrewAI Platform
|
||||
|
||||
Na CrewAI Platform, navegue até **Settings** → **Secret Provider Credentials** e clique em **Add Credential**.
|
||||
|
||||
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
|
||||
{/* SCREENSHOT: Empty state of Secret Provider Credentials page with "Add Credential" button → /images/secrets-manager/usage/02-amp-credentials-empty-state.png */}
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Chaves de acesso estáticas">
|
||||
Preencha o formulário:
|
||||
|
||||
- **Name:** Um nome descritivo, ex. `aws-prod`.
|
||||
- **Provider:** `AWS Secrets Manager`.
|
||||
- **Region:** A região AWS onde seus segredos vivem, ex. `us-east-1`. Deve corresponder à região dos segredos que você quer ler.
|
||||
- **Access Key ID:** O valor do Passo 4.
|
||||
- **Secret Access Key:** O valor do Passo 4.
|
||||
- (Opcional) Marque **Set as default credential for this provider**. A credencial padrão é usada por variáveis de ambiente que referenciam segredos AWS sem especificar uma credencial explicitamente.
|
||||
|
||||
Deixe **Role ARN** e **External ID** em branco.
|
||||
|
||||
Clique em **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + static access keys filled in → /images/secrets-manager/usage/03a-amp-add-credential-form-aws-static.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="AssumeRole">
|
||||
Preencha o formulário:
|
||||
|
||||
- **Name:** Um nome descritivo, ex. `aws-prod-assumerole`.
|
||||
- **Provider:** `AWS Secrets Manager`.
|
||||
- **Region:** A região AWS onde seus segredos vivem.
|
||||
- **Access Key ID:** A access key do usuário IAM do Passo 4 (usada para chamar o STS).
|
||||
- **Secret Access Key:** A secret access key do usuário IAM do Passo 4.
|
||||
- **Role ARN:** O Role ARN que você copiou no Passo 4.
|
||||
- **External ID:** O External ID que você definiu na trust policy do role (omita se não houver).
|
||||
- (Opcional) Marque **Set as default credential for this provider**.
|
||||
|
||||
Clique em **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + AssumeRole fields filled in → /images/secrets-manager/usage/03b-amp-add-credential-form-aws-assumerole.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
**Como os dois modos se comportam em runtime:**
|
||||
|
||||
- Com apenas **chaves de acesso estáticas**, a CrewAI Platform chama o AWS Secrets Manager diretamente usando as chaves que você forneceu.
|
||||
- Quando um **Role ARN** está definido, a CrewAI Platform primeiro chama `sts:AssumeRole` com as chaves de acesso fornecidas (e External ID se configurado), depois usa as credenciais de curta duração retornadas pelo STS para ler seus segredos.
|
||||
</Note>
|
||||
|
||||
{/* SCREENSHOT: Credentials list showing the new AWS row, with "(default)" badge if applicable → /images/secrets-manager/usage/04-amp-credential-created.png */}
|
||||
|
||||
## Passo 6 — Criar Pelo Menos Um Segredo na AWS
|
||||
|
||||
Se você ainda não tem segredos no AWS Secrets Manager, crie um agora para que possa verificar a conexão no Passo 7.
|
||||
|
||||
No [console do AWS Secrets Manager](https://console.aws.amazon.com/secretsmanager/), clique em **Store a new secret**.
|
||||
|
||||
- **Secret type:** Escolha **Other type of secret**.
|
||||
- **Key/value pairs** — ou:
|
||||
- Informe um ou mais pares chave/valor (recomendado para segredos estruturados), ou
|
||||
- Use a aba **Plaintext** para um único valor de string.
|
||||
- **Encryption key:** Use `aws/secretsmanager` (a chave gerenciada pela AWS) a menos que você tenha um requisito específico de chave KMS.
|
||||
|
||||
Clique em **Next**, então informe:
|
||||
|
||||
- **Secret name:** Um nome único, ex. `crewai/openai-api-key`.
|
||||
- **Description (optional):** Uma nota curta sobre o propósito do segredo.
|
||||
|
||||
Clique em **Next** pelos passos de rotação e revisão, depois clique em **Store**.
|
||||
|
||||
<Note>
|
||||
**Sintaxe de referência por chave JSON.** Se você armazenar um segredo com múltiplos pares chave/valor (um objeto JSON), a CrewAI Platform pode extrair um campo específico usando a sintaxe `secret-name#json_key` em referências de variáveis de ambiente. Por exemplo, um segredo chamado `database-credentials` com `{"username": "...", "password": "..."}` pode ser referenciado como `database-credentials#password`. Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) para detalhes.
|
||||
</Note>
|
||||
|
||||
Para detalhes completos, veja a documentação da AWS: [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html).
|
||||
|
||||
{/* SCREENSHOT: AWS Secrets Manager "Choose secret type" page → /images/secrets-manager/aws/07-create-secret-store-type.png */}
|
||||
{/* SCREENSHOT: AWS Secrets Manager "Configure secret" page with name and description → /images/secrets-manager/aws/08-create-secret-name.png */}
|
||||
|
||||
## Passo 7 — Testar a Conexão
|
||||
|
||||
De volta à CrewAI Platform, na página **Secret Provider Credentials**, encontre a credencial que você acabou de criar e clique em **Test Connection**.
|
||||
|
||||
Um toast de sucesso confirma que a CrewAI Platform consegue se autenticar na AWS e ler segredos da sua conta.
|
||||
|
||||
{/* SCREENSHOT: Success toast after clicking "Test Connection" → /images/secrets-manager/usage/05-amp-test-connection-success.png */}
|
||||
|
||||
Se o teste falhar, verifique as causas mais comuns:
|
||||
|
||||
| Sintoma | Causa provável |
|
||||
|---|---|
|
||||
| `AccessDenied` em `secretsmanager:ListSecrets` | Política não anexada, ou usuário errado. Reconfira o Passo 3. |
|
||||
| `AccessDenied` em `kms:Decrypt` | Falta a declaração `KMSDecrypt`, ou seus segredos usam uma chave KMS gerenciada pelo cliente não coberta por `Resource: "*"`. |
|
||||
| `InvalidClientTokenId` / `SignatureDoesNotMatch` | Access key ID ou secret access key errados. Reconfira os Passos 4 e 5. |
|
||||
| `RegionDisabledException` / nenhum segredo encontrado | A **Region** da credencial não corresponde a onde seus segredos realmente vivem. |
|
||||
| `AccessDenied` em `sts:AssumeRole` (apenas AssumeRole) | Política inline `sts:AssumeRole` ausente no usuário IAM, ou a trust policy do role não permite este principal, ou o External ID não corresponde. |
|
||||
| Teste passa imediatamente após criar o usuário IAM, mas falha da próxima vez | Credenciais IAM às vezes levam um ou dois minutos para se propagar globalmente. Tente novamente. |
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
Agora que a AWS está conectada, vá para [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage) para:
|
||||
|
||||
- Conceder aos membros da organização as permissões corretas para usar (ou gerenciar) o Secrets Manager.
|
||||
- Referenciar seus segredos AWS a partir de variáveis de ambiente da CrewAI Platform.
|
||||
|
||||
Se você quiser segredos **conscientes de rotação** que se propagam sem novo deploy, mude para [AWS Workload Identity (Federação OIDC)](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) — mesmo cofre de segredos, sem credenciais estáticas, segredos buscados por kickoff.
|
||||
@@ -0,0 +1,275 @@
|
||||
---
|
||||
title: Azure Workload Identity Federation
|
||||
description: Configure o Azure Key Vault via Microsoft Entra Workload Identity Federation para acesso a segredos consciente de rotação e sem credenciais
|
||||
sidebarTitle: Com Workload Identity
|
||||
icon: "id-badge"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Este guia configura o Azure Key Vault como provedor de segredos usando **Microsoft Entra Workload Identity Federation**: a CrewAI Platform emite tokens OIDC de curta duração, os troca por um token de acesso do Entra via Microsoft identity platform e lê seus segredos — sem nenhum client secret armazenado em lugar algum.
|
||||
|
||||
<Note>
|
||||
**Por que este caminho:** os segredos são resolvidos no momento de execução da automação, então **valores rotacionados se propagam para o próximo kickoff sem novo deploy**. Se você só precisa de credenciais estáticas, veja o guia mais simples [Azure Key Vault — client secret](/pt-BR/enterprise/features/secrets-manager/azure).
|
||||
</Note>
|
||||
|
||||
### Como funciona em runtime
|
||||
|
||||
1. O worker do deployment solicita um JWT OIDC fresco à CrewAI Platform.
|
||||
2. O worker apresenta o JWT ao Microsoft Entra em `https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token` como um `client_assertion` (`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`), referenciando o App Registration cujo **Federated Identity Credential** corresponde ao issuer + subject do JWT.
|
||||
3. O Entra valida o JWT contra o documento de discovery OIDC e JWKS da sua plataforma, então retorna um token de acesso de curta duração com escopo `https://vault.azure.net/.default`.
|
||||
4. O worker chama o Azure Key Vault para ler o segredo.
|
||||
5. O valor obtido é injetado como valor da variável de ambiente para aquele kickoff de automação.
|
||||
|
||||
Tokens OIDC subject são cacheados por ~1 hora para evitar reemissão a cada kickoff. Valores de segredos são buscados frescos a cada kickoff independentemente do estado do cache OIDC, e é isso que torna este caminho consciente de rotação.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
<Note>
|
||||
Antes de começar, certifique-se de que você tem:
|
||||
|
||||
- A imagem do pod de automação deve incluir o runtime da CrewAI versão `1.14.5` ou superior.
|
||||
- Uma subscription Azure e um tenant Microsoft Entra que você possa gerenciar.
|
||||
- Permissão no tenant para criar App Registrations e adicionar Federated Identity Credentials.
|
||||
- Um Key Vault usando **Azure RBAC** para autorização (não o modelo legado de access-policy).
|
||||
- Uma organização na CrewAI Platform onde seu usuário tem as permissões `workload_identity_configs: manage` e `secret_providers: manage`. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac).
|
||||
- **Sua instalação da CrewAI Platform deve ser acessível a partir do Microsoft Entra via HTTPS** para que o Entra possa buscar o documento de discovery OIDC e o JWKS durante a validação do token. Confirme com o administrador da sua plataforma que o host é acessível pela internet.
|
||||
</Note>
|
||||
|
||||
## Passo 1 — Encontre a URL do Issuer OIDC da Sua CrewAI Platform
|
||||
|
||||
Sua instalação da CrewAI Platform publica um documento de discovery OpenID Connect em `https://<your-platform-host>/.well-known/openid-configuration`. O campo `issuer` ali é a URL que o Microsoft Entra registrará como issuer de federação confiável.
|
||||
|
||||
Abra a URL em um navegador:
|
||||
|
||||
```
|
||||
https://<your-platform-host>/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
Você deverá ver um JSON contendo:
|
||||
|
||||
```json
|
||||
{
|
||||
"issuer": "https://<your-platform-host>",
|
||||
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Anote o valor exato de `issuer` — você o usará no Passo 3.
|
||||
|
||||
<Tip>
|
||||
Se a URL retornar 404 ou 503, contate o administrador da sua plataforma. O issuer OIDC requer uma chave de assinatura privada configurada no momento da instalação. Veja o guia de instalação da plataforma para as configurações `OIDC_PRIVATE_KEY` e `OIDC_ISSUER`.
|
||||
</Tip>
|
||||
|
||||
## Passo 2 — Criar um App Registration
|
||||
|
||||
No [portal Microsoft Entra](https://entra.microsoft.com), navegue até **App registrations** e clique em **New registration**.
|
||||
|
||||
- **Name:** `crewai-secrets-reader`
|
||||
- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`.
|
||||
- Deixe **Redirect URI** em branco.
|
||||
|
||||
Clique em **Register**. Anote o **Application (client) ID** e o **Directory (tenant) ID** no blade de visão geral do App — você os usará no Passo 6.
|
||||
|
||||
{/* SCREENSHOT: Azure portal "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure-wi/01-register-app.png */}
|
||||
|
||||
## Passo 3 — Adicionar um Federated Identity Credential
|
||||
|
||||
O Federated Identity Credential diz ao Microsoft Entra: *confie em JWTs emitidos por este issuer, com este subject, quando forem apresentados como client assertion para este App Registration.*
|
||||
|
||||
No App Registration, navegue até **Certificates & secrets** → **Federated credentials** → **Add credential**.
|
||||
|
||||
- **Federated credential scenario:** `Other issuer`.
|
||||
- **Issuer:** a URL do issuer da CrewAI Platform do Passo 1, ex. `https://<your-platform-host>`.
|
||||
- **Subject identifier:** `organization:<YOUR_CREWAI_ORG_UUID>` — exatamente o valor da claim `sub` do JWT. Encontre o UUID da sua org nas configurações de organização da CrewAI Platform. Isso escopa a federação a uma organização CrewAI específica — apenas tokens emitidos para as automações dessa org são aceitos.
|
||||
- **Name:** qualquer label descritivo, ex. `crewai-org-prod`.
|
||||
- **Audience:** `api://AzureADTokenExchange`. Esta é a audience fixa que o Microsoft Entra requer para federated credentials e é o que a CrewAI Platform define na claim `aud` do JWT.
|
||||
|
||||
Clique em **Add**.
|
||||
|
||||
<Tip>
|
||||
**Isolamento por organização.** O subject identifier (`organization:<UUID>`) restringe o federated credential aos tokens de uma organização CrewAI específica. Se múltiplas organizações CrewAI devem compartilhar um App Registration, adicione um Federated Identity Credential por organização (cada um com o UUID da org).
|
||||
</Tip>
|
||||
|
||||
Para detalhes completos, veja a documentação da Microsoft: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust).
|
||||
|
||||
{/* SCREENSHOT: "Add credential" panel with scenario = "Other issuer", issuer URL, subject "organization:<uuid>", audience "api://AzureADTokenExchange" → /images/secrets-manager/azure-wi/02-add-federated-credential.png */}
|
||||
|
||||
## Passo 4 — Conceder ao App Registration Acesso ao Key Vault
|
||||
|
||||
Conceda ao App Registration **Key Vault Secrets User** no vault de destino — o mesmo papel que você usaria para o caminho de credenciais estáticas. Use a nível de vault (mais simples) ou por segredo (menor privilégio).
|
||||
|
||||
<Tabs>
|
||||
<Tab title="A nível de vault (mais simples)">
|
||||
```bash
|
||||
az role assignment create \
|
||||
--assignee <APPLICATION_CLIENT_ID> \
|
||||
--role "Key Vault Secrets User" \
|
||||
--scope $(az keyvault show --name <VAULT_NAME> --query id -o tsv)
|
||||
```
|
||||
|
||||
O escopo a nível de vault concede a permissão `secrets/list` da qual o **autocomplete de Secret Name** no formulário de env-var da CrewAI Platform depende. Escolha esta aba se você quer que o autocomplete funcione.
|
||||
|
||||
{/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure-wi/03-grant-vault-rbac.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="Por segredo (menor privilégio)">
|
||||
```bash
|
||||
az role assignment create \
|
||||
--assignee <APPLICATION_CLIENT_ID> \
|
||||
--role "Key Vault Secrets User" \
|
||||
--scope $(az keyvault secret show --vault-name <VAULT_NAME> --name <SECRET_NAME> --query id -o tsv)
|
||||
```
|
||||
|
||||
Vínculos por segredo desabilitam o **autocomplete de Secret Name** no formulário de env-var da CrewAI Platform (o autocomplete requer `secrets/list`, que é escopado apenas por vault). Digite o nome completo do segredo.
|
||||
|
||||
{/* SCREENSHOT: Per-secret IAM panel with the App Registration assigned **Key Vault Secrets User** at the secret resource scope → /images/secrets-manager/azure-wi/04-per-secret-rbac.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="Portal (UI)">
|
||||
Para uma atribuição **a nível de vault**:
|
||||
|
||||
1. Abra seu Key Vault no portal Azure.
|
||||
2. Clique em **Access control (IAM)** → **Add** → **Add role assignment**.
|
||||
3. Selecione o papel **Key Vault Secrets User** → **Next**.
|
||||
4. Clique em **Select members**, procure pelo App Registration `crewai-secrets-reader`, clique em **Select**.
|
||||
5. Clique em **Review + assign**.
|
||||
|
||||
Para uma atribuição **por segredo**, use o mesmo fluxo, mas comece em **Objects** → **Secrets** → selecione o segredo → seu próprio painel **Access control (IAM)**. Vínculos por segredo desabilitam o autocomplete (veja a aba Por segredo acima).
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Passo 5 — Criar Pelo Menos Um Segredo no Key Vault
|
||||
|
||||
Se você ainda não tem um segredo para testar, crie um via Azure CLI:
|
||||
|
||||
```bash
|
||||
az keyvault secret set \
|
||||
--vault-name <VAULT_NAME> \
|
||||
--name openai-api-key \
|
||||
--value "sk-your-actual-key"
|
||||
```
|
||||
|
||||
Ou via portal Azure:
|
||||
|
||||
1. Abra seu Key Vault e navegue até **Objects** → **Secrets**.
|
||||
2. Clique em **Generate/Import**.
|
||||
3. **Upload options:** `Manual`. **Name:** o nome do segredo (ex. `openai-api-key`). **Secret value:** cole o valor.
|
||||
4. Clique em **Create**.
|
||||
|
||||
<Note>
|
||||
**Convenções de nome de segredo.** Nomes de segredos do Azure Key Vault não podem conter underscores. A CrewAI Platform converte automaticamente underscores em hífens ao chamar o Azure (ex.: `db_password` é enviado como `db-password`), então você pode manter nomes de env-var no estilo underscore — mas o segredo subjacente no Key Vault deve usar hífens.
|
||||
</Note>
|
||||
|
||||
## Passo 6 — Adicionar uma Configuração de Workload Identity na CrewAI Platform
|
||||
|
||||
Na CrewAI Platform, navegue até **Settings** → **Workload Identity** e clique em **Add Workload Identity Config**.
|
||||
|
||||
Preencha o formulário:
|
||||
|
||||
- **Name:** Um nome descritivo, ex. `azure-prod`.
|
||||
- **Cloud Provider:** `Azure`.
|
||||
- **Tenant ID:** seu **Directory (tenant) ID** do Microsoft Entra do Passo 2.
|
||||
- **Client ID:** o **Application (client) ID** do seu App Registration do Passo 2.
|
||||
- (Opcional) Marque **Set as default for Azure** se você quiser que esta seja a config WI padrão selecionada ao criar uma credencial de segredo baseada em Azure.
|
||||
|
||||
A **Audience** é fixa em `api://AzureADTokenExchange` — o Microsoft Entra requer exatamente essa audience para federated credentials, então nenhum campo Audience é mostrado no formulário.
|
||||
|
||||
Clique em **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Workload Identity Config" form with Azure, tenant ID, client ID populated → /images/secrets-manager/azure-wi/05-amp-add-wi-config-azure.png */}
|
||||
{/* SCREENSHOT: Workload Identity list showing AWS, GCP, and Azure rows → /images/secrets-manager/azure-wi/06-amp-wi-list-with-azure.png */}
|
||||
|
||||
## Passo 7 — Adicionar uma Credencial de Provedor de Segredos Vinculada à Config WI
|
||||
|
||||
Navegue até **Settings** → **Secret Provider Credentials** e clique em **Add Credential**.
|
||||
|
||||
Preencha o formulário:
|
||||
|
||||
- **Name:** Um nome descritivo, ex. `azure-prod-wi`.
|
||||
- **Provider:** `Azure Key Vault`.
|
||||
- **Authentication Method:** `Workload Identity`.
|
||||
- **Workload Identity Configuration:** selecione a config que você criou no Passo 6.
|
||||
- **Key Vault URL:** o hostname DNS do vault, ex. `https://my-vault.vault.azure.net`.
|
||||
- (Opcional) Marque **Set as default credential for this provider**.
|
||||
|
||||
O formulário pedirá apenas a **Key Vault URL** sob Workload Identity — os campos de credencial estática (Tenant ID, Client ID, Client Secret) estão intencionalmente ocultos porque não se aplicam a este caminho; tenant + client vêm da config WI vinculada.
|
||||
|
||||
Clique em **Create**.
|
||||
|
||||
<Tip>
|
||||
**Um App Registration, muitos vaults.** A Key Vault URL fica na credencial, não na config WI. Então um App Registration (e uma config WI) pode servir múltiplos Key Vaults — basta criar uma Secret Provider Credential por vault, todas vinculadas à mesma config WI.
|
||||
</Tip>
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure + Workload Identity + WI config dropdown + vault URL → /images/secrets-manager/azure-wi/07-amp-add-credential-azure-wi.png */}
|
||||
|
||||
## Passo 8 — Testar a Conexão
|
||||
|
||||
Depois de salvar a credencial, clique em **Test Connection**. Para credenciais workload-identity isso verifica o handshake OIDC: a CrewAI Platform emite um JWT, apresenta-o ao Microsoft Entra como um `client_assertion` federado, e confirma que o Entra retorna um token de acesso escopado para o vault. Um resultado verde significa que o vínculo de federação está saudável.
|
||||
|
||||
Um Test Connection bem-sucedido prova que o issuer, subject e audience do Federated Identity Credential correspondem todos, e que o App Registration é acessível. Ele **não** prova que o RBAC por segredo do Key Vault está correto — `getSecret` contra um segredo específico é exercitado separadamente quando uma variável de ambiente é resolvida no kickoff. Veja [Solução de Problemas](#troubleshooting) para modos de falha de handshake.
|
||||
|
||||
## Passo 9 — Referenciar o Segredo em uma Variável de Ambiente
|
||||
|
||||
Referencie o segredo em uma automação, exatamente como você faria para qualquer outra env var apoiada pelo Secrets Manager. Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) para os campos do formulário e o comportamento.
|
||||
|
||||
## Passo 10 — Verificar a Rotação
|
||||
|
||||
Após o deployment estar rodando, rotacione o segredo no Key Vault:
|
||||
|
||||
```bash
|
||||
az keyvault secret set \
|
||||
--vault-name <VAULT_NAME> \
|
||||
--name openai-api-key \
|
||||
--value "rotated value"
|
||||
```
|
||||
|
||||
Dispare um novo kickoff de automação. O ambiente do kickoff verá `"rotated value"` — sem novo deploy, sem reinício de worker, sem espera de TTL.
|
||||
|
||||
Para confirmar nos logs do worker, procure por:
|
||||
|
||||
```
|
||||
Workload identity config '<id>' (azure): N secret(s) resolved
|
||||
```
|
||||
|
||||
Esta linha aparece para cada kickoff e indica uma chamada `getSecret` fresca contra o Azure Key Vault.
|
||||
|
||||
Para uma verificação de ponta a ponta baseada em fingerprint, veja [Verificar Rotação de Ponta a Ponta](/pt-BR/enterprise/features/secrets-manager/verify-rotation).
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
| Sintoma | Causa provável |
|
||||
|---|---|
|
||||
| Test Connection falha com erro de handshake | O `client_assertion` federado foi rejeitado pelo Microsoft Entra. Verifique se o **Issuer** do Federated Identity Credential corresponde exatamente ao valor `issuer` da plataforma, se **Subject** é `organization:<your-org-uuid>` (correspondendo à claim `sub` do JWT), se **Audience** é `api://AzureADTokenExchange` e se a URL de discovery OIDC da plataforma é acessível a partir do Entra pela internet pública. |
|
||||
| `AADSTS70021: No matching federated identity record found for presented assertion` | O **Issuer** + **Subject** + **Audience** do Federated Identity Credential não correspondem todos exatamente ao JWT. Reconfira o Passo 3: subject deve ser `organization:<your-org-uuid>` (correspondendo à claim `sub` do JWT), audience deve ser `api://AzureADTokenExchange`. |
|
||||
| `AADSTS700024: Client assertion is not within its valid time range` | O relógio do host da CrewAI Platform está significativamente fora do tempo real. Verifique o NTP no host. |
|
||||
| `AADSTS50013: Assertion failed signature validation` | O Microsoft Entra não conseguiu verificar a assinatura do JWT. Confirme que `https://<your-platform-host>/oauth2/jwks` é acessível pela internet pública e serve um JWKS válido. |
|
||||
| Autocomplete de Secret Name mostra `Forbidden — does not have permission to perform action 'Microsoft.KeyVault/vaults/secrets/.../list'` | O papel **Key Vault Secrets User** do App Registration está escopado a um único segredo. Conceda o papel no escopo do vault para que a ação de plano de dados `list` seja permitida. Veja o Passo 4. |
|
||||
| Kickoff falha ao resolver um segredo mesmo que o Test Connection passe | O vínculo WI está saudável, mas o RBAC por segredo do Key Vault está ausente no segredo que falha. Audite **Key Vault Secrets User** naquele segredo específico (ou estenda a atribuição de papel ao escopo do vault). |
|
||||
| `Forbidden — request was not authorized` (vault usando access policies legadas) | O vault não foi alternado para Azure RBAC. Sob **Access configuration** do vault, defina o modelo de permissão para **Azure role-based access control** e reconceda o papel do Passo 4. |
|
||||
| `azure_vault_url is required for Azure secret resolution` (logs do worker) | A Secret Provider Credential está sem a **Key Vault URL**. Reconfira o Passo 7. |
|
||||
| Valor rotacionado não é pego no próximo kickoff | Confirme que a env var na automação está referenciando uma credencial baseada em Workload Identity (não uma credencial de chaves estáticas). O caminho estático incorpora valores à imagem do deploy. |
|
||||
|
||||
### Links de Referência
|
||||
|
||||
- Microsoft: [Microsoft Entra Workload Identity Federation overview](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation)
|
||||
- Microsoft: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust)
|
||||
- Microsoft: [Azure Key Vault RBAC guide](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide)
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
- [Use segredos em variáveis de ambiente e gerencie permissões](/pt-BR/enterprise/features/secrets-manager/usage)
|
||||
- Para multi-cloud, a configuração equivalente para AWS está em [AWS Workload Identity (Federação OIDC)](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) e a equivalente para GCP em [GCP Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity).
|
||||
|
||||
## Referência de Screenshots
|
||||
|
||||
Os placeholders acima mapeiam para:
|
||||
|
||||
- `01-register-app.png` — formulário "Register an application" do portal Azure preenchido com `crewai-secrets-reader`.
|
||||
- `02-add-federated-credential.png` — App Registration → Certificates & secrets → Federated credentials → Add credential, com **Other issuer**, a URL do issuer da plataforma, subject `organization:<uuid>`, audience `api://AzureADTokenExchange`.
|
||||
- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, com **Key Vault Secrets User** e o App Registration selecionado.
|
||||
- `04-per-secret-rbac.png` — mesmo formulário, mas no escopo IAM de um único segredo (caminho alternativo de menor privilégio).
|
||||
- `05-amp-add-wi-config-azure.png` — formulário "Add Workload Identity Config" da CrewAI Platform com Cloud Provider = Azure, Tenant ID, Client ID preenchidos.
|
||||
- `06-amp-wi-list-with-azure.png` — página de listagem do Workload Identity após criação, mostrando linhas para AWS, GCP e a nova config Azure.
|
||||
- `07-amp-add-credential-azure-wi.png` — formulário "Add Secret Provider Credential" com Provider = Azure Key Vault, Auth = Workload Identity, a config WI escolhida e Key Vault URL preenchida.
|
||||
196
docs/edge/pt-BR/enterprise/features/secrets-manager/azure.mdx
Normal file
196
docs/edge/pt-BR/enterprise/features/secrets-manager/azure.mdx
Normal file
@@ -0,0 +1,196 @@
|
||||
---
|
||||
title: Azure Key Vault
|
||||
description: Configure o Azure Key Vault como provedor de segredos para a CrewAI Platform, de ponta a ponta
|
||||
sidebarTitle: Com Credenciais Estáticas
|
||||
icon: "key"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Este guia o orienta na configuração do Azure Key Vault como provedor de segredos para sua organização na CrewAI Platform, usando um **Microsoft Entra App Registration com client secret**. Ao final, a CrewAI Platform poderá ler segredos armazenados no seu Azure Key Vault e injetá-los como valores de variáveis de ambiente em runtime.
|
||||
|
||||
<Note>
|
||||
Este guia cobre o caminho de **credenciais estáticas** — segredos são resolvidos no momento do deploy e incorporados à imagem do deployment. Valores rotacionados exigem um novo deploy. Se você quiser segredos conscientes de rotação que se atualizam a cada kickoff de automação, veja [Azure Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity).
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Este guia cobre a configuração do lado Azure e a configuração da credencial na CrewAI Platform. Para então referenciar um segredo a partir de uma variável de ambiente, veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage).
|
||||
</Note>
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
<Note>
|
||||
Antes de começar, certifique-se de que você tem:
|
||||
|
||||
- Uma subscription Azure com permissão para criar App Registrations no Microsoft Entra e para conceder atribuições de papéis em recursos do Key Vault.
|
||||
- Um Key Vault usando **Azure RBAC** para autorização (não o modelo legado de access-policy). Se o seu vault ainda usa access policies, mude-o para RBAC sob o blade **Access configuration** do vault.
|
||||
- Uma organização na CrewAI Platform onde seu usuário tem a permissão `secret_providers: manage`. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac).
|
||||
</Note>
|
||||
|
||||
## Passo 1 — Criar um App Registration
|
||||
|
||||
O App Registration é a identidade do lado Microsoft Entra como a qual a CrewAI Platform irá se autenticar.
|
||||
|
||||
No [portal Microsoft Entra](https://entra.microsoft.com), navegue até **App registrations** e clique em **New registration**.
|
||||
|
||||
- **Name:** `crewai-secrets-reader`
|
||||
- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`.
|
||||
- Deixe **Redirect URI** em branco.
|
||||
|
||||
Clique em **Register**. Anote o **Application (client) ID** e o **Directory (tenant) ID** no blade de visão geral do App — você colará ambos na CrewAI Platform no Passo 4.
|
||||
|
||||
Para detalhes completos, veja a documentação da Microsoft: [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
|
||||
|
||||
{/* SCREENSHOT: Azure "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure/01-register-app.png */}
|
||||
|
||||
## Passo 2 — Criar um Client Secret
|
||||
|
||||
No App Registration, navegue até **Certificates & secrets** → **Client secrets** → **New client secret**.
|
||||
|
||||
- **Description:** `crewai-platform`
|
||||
- **Expires:** escolha uma duração que corresponda à sua política de rotação (a Microsoft limita isso em 24 meses).
|
||||
|
||||
Clique em **Add**. Copie a coluna **Value** imediatamente — ela nunca pode ser re-exibida depois que você sair da página.
|
||||
|
||||
<Warning>
|
||||
Client secrets são credenciais estáticas de longa duração. Armazene o valor com segurança (em um gerenciador de senhas ou no seu próprio cofre de segredos) e rotacione-o antes da expiração. Para eliminar credenciais estáticas completamente, use [Azure Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity).
|
||||
</Warning>
|
||||
|
||||
{/* SCREENSHOT: "Client secrets" tab with the new secret row and the "Value" column highlighted → /images/secrets-manager/azure/02-create-client-secret.png */}
|
||||
|
||||
## Passo 3 — Conceder ao App Registration Acesso ao Key Vault
|
||||
|
||||
A CrewAI Platform precisa de acesso de leitura aos segredos no seu Key Vault. Use um de dois escopos — **a nível de vault** para simplicidade, ou **por segredo** para menor privilégio.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="A nível de vault (mais simples)">
|
||||
No [console do Key Vault](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults), abra o vault de destino, depois navegue até **Access control (IAM)** → **Add** → **Add role assignment**.
|
||||
|
||||
- **Role:** **Key Vault Secrets User**
|
||||
- **Assign access to:** User, group, or service principal
|
||||
- **Members:** procure e selecione seu App Registration (`crewai-secrets-reader`).
|
||||
|
||||
Clique em **Review + assign**.
|
||||
|
||||
Ou via Azure CLI:
|
||||
|
||||
```bash
|
||||
az role assignment create \
|
||||
--assignee <APPLICATION_CLIENT_ID> \
|
||||
--role "Key Vault Secrets User" \
|
||||
--scope $(az keyvault show --name <VAULT_NAME> --query id -o tsv)
|
||||
```
|
||||
|
||||
{/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure/03-grant-vault-rbac.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="Por segredo (menor privilégio)">
|
||||
Conceda o papel a nível de um segredo individual. Repita para cada segredo que a CrewAI Platform deve acessar:
|
||||
|
||||
```bash
|
||||
az role assignment create \
|
||||
--assignee <APPLICATION_CLIENT_ID> \
|
||||
--role "Key Vault Secrets User" \
|
||||
--scope $(az keyvault secret show --vault-name <VAULT_NAME> --name <SECRET_NAME> --query id -o tsv)
|
||||
```
|
||||
|
||||
{/* SCREENSHOT: Per-secret "Access control (IAM)" panel showing role assignment scoped to one secret → /images/secrets-manager/azure/04-per-secret-rbac.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
O papel **Key Vault Secrets User** permite ler valores de segredos, mas não listar todos os segredos no vault. O autocomplete de nome de segredo da CrewAI Platform também chama `list` — essa permissão está incluída no papel no escopo de vault, mas **não** no escopo por segredo. Com vínculos por segredo, o autocomplete não sugerirá segredos; digite o nome completo do segredo.
|
||||
</Tip>
|
||||
|
||||
## Passo 4 — Adicionar a Credencial na CrewAI Platform
|
||||
|
||||
Na CrewAI Platform, navegue até **Settings** → **Secret Provider Credentials** e clique em **Add Credential**.
|
||||
|
||||
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
|
||||
|
||||
Preencha o formulário:
|
||||
|
||||
- **Name:** Um nome descritivo, ex. `azure-prod`.
|
||||
- **Provider:** `Azure Key Vault`.
|
||||
- **Key Vault URL:** o hostname DNS do vault, ex. `https://my-vault.vault.azure.net`.
|
||||
- **Tenant ID:** seu **Directory (tenant) ID** do Microsoft Entra do Passo 1.
|
||||
- **Client ID:** o **Application (client) ID** do seu App Registration do Passo 1.
|
||||
- **Client Secret:** o **Value** que você copiou no Passo 2.
|
||||
- (Opcional) Marque **Set as default credential for this provider**. A credencial padrão é usada por variáveis de ambiente que referenciam segredos Azure sem especificar uma credencial explicitamente.
|
||||
|
||||
Clique em **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure fields filled in → /images/secrets-manager/azure/05-amp-add-credential-form-azure.png */}
|
||||
|
||||
## Passo 5 — Criar Pelo Menos Um Segredo no Azure Key Vault
|
||||
|
||||
Se você ainda não tem segredos no Key Vault, crie um agora para que possa verificar a conexão no Passo 6.
|
||||
|
||||
No console do Key Vault, navegue até **Objects** → **Secrets** → **Generate/Import**.
|
||||
|
||||
- **Upload options:** `Manual`
|
||||
- **Name:** ex. `openai-api-key`
|
||||
- **Secret value:** cole o valor do seu segredo
|
||||
- Deixe o resto nos padrões.
|
||||
|
||||
Clique em **Create**.
|
||||
|
||||
Ou via Azure CLI:
|
||||
|
||||
```bash
|
||||
az keyvault secret set \
|
||||
--vault-name <VAULT_NAME> \
|
||||
--name openai-api-key \
|
||||
--value "sk-your-actual-key"
|
||||
```
|
||||
|
||||
<Note>
|
||||
**Convenções de nome de segredo.** Nomes de segredos do Azure Key Vault não podem conter underscores. A CrewAI Platform converte automaticamente underscores em hífens ao chamar o Azure (ex.: `db_password` é enviado como `db-password`), então você pode manter nomes de env-var no estilo underscore — mas o segredo subjacente no Key Vault deve usar hífens.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
**Sintaxe de referência por chave JSON.** O Key Vault trata valores de segredos como strings opacas. Se o valor do seu segredo for um objeto JSON, a CrewAI Platform pode extrair um único campo usando a sintaxe `secret-name#json_key` (ex. `database-credentials#password`). Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) para detalhes.
|
||||
</Note>
|
||||
|
||||
Para detalhes completos, veja a documentação da Microsoft: [Set and retrieve a secret](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-cli).
|
||||
|
||||
{/* SCREENSHOT: Azure Key Vault "Create a secret" form with name and value → /images/secrets-manager/azure/06-create-secret.png */}
|
||||
|
||||
## Passo 6 — Testar a Conexão
|
||||
|
||||
De volta à CrewAI Platform, na página **Secret Provider Credentials**, encontre a credencial que você acabou de criar e clique em **Test Connection**.
|
||||
|
||||
Um toast de sucesso confirma que a CrewAI Platform consegue se autenticar no Microsoft Entra e ler segredos do seu vault.
|
||||
|
||||
{/* SCREENSHOT: Success toast after clicking "Test Connection" on the Azure credential → /images/secrets-manager/azure/07-test-connection-success.png */}
|
||||
|
||||
Se o teste falhar, verifique as causas mais comuns:
|
||||
|
||||
| Sintoma | Causa provável |
|
||||
|---|---|
|
||||
| `AADSTS7000215: Invalid client secret provided` | O **Client Secret** colado está errado ou expirado. Recrie o segredo (Passo 2) e atualize a credencial. |
|
||||
| `AADSTS700016: Application not found in the directory` | O **Tenant ID** ou **Client ID** não corresponde ao App Registration. Reconfira o Passo 4. |
|
||||
| `Forbidden — caller does not have permission` | O App Registration está sem o papel **Key Vault Secrets User** no vault (ou por segredo). Reconfira o Passo 3. |
|
||||
| `Vault not found` / erros de DNS | A **Key Vault URL** está errada, ou seu vault tem endpoints privados que bloqueiam acesso público. Confirme que o host responde a `curl https://<vault-name>.vault.azure.net/secrets?api-version=7.4`. |
|
||||
| `Forbidden — request was not authorized` (vault usando access policies legadas) | O vault não foi alternado para Azure RBAC. Sob **Access configuration** do vault, defina o modelo de permissão para **Azure role-based access control** e reconceda o papel do Passo 3. |
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
Agora que o Azure Key Vault está conectado, vá para [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage) para:
|
||||
|
||||
- Conceder aos membros da organização as permissões corretas para usar (ou gerenciar) o Secrets Manager.
|
||||
- Referenciar seus segredos Azure a partir de variáveis de ambiente da CrewAI Platform.
|
||||
|
||||
Se você quiser segredos **conscientes de rotação** que se propagam sem novo deploy, mude para [Azure Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity) — mesmo vault, sem client secret para rotacionar, segredos buscados por kickoff.
|
||||
|
||||
## Referência de Screenshots
|
||||
|
||||
Os placeholders acima mapeiam para:
|
||||
|
||||
- `01-register-app.png` — formulário "Register an application" do portal Azure preenchido com `crewai-secrets-reader`.
|
||||
- `02-create-client-secret.png` — App Registration → Certificates & secrets → Client secrets, com a linha do segredo recém-criado visível (coluna Value destacada antes de ser mascarada).
|
||||
- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, com **Key Vault Secrets User** escolhido e o App Registration selecionado como membro.
|
||||
- `04-per-secret-rbac.png` — mesmo painel, mas escopado para um único recurso de segredo (caminho alternativo de menor privilégio).
|
||||
- `05-amp-add-credential-form-azure.png` — formulário "Add Secret Provider Credential" da CrewAI Platform: Provider = Azure Key Vault, todos os cinco campos preenchidos.
|
||||
- `06-create-secret.png` — painel "Create a secret" do Azure Key Vault com `openai-api-key` e um valor colado.
|
||||
- `07-test-connection-success.png` — toast de sucesso / estado da linha na CrewAI Platform após clicar em **Test Connection** na credencial.
|
||||
@@ -0,0 +1,273 @@
|
||||
---
|
||||
title: GCP Workload Identity Federation
|
||||
description: Configure o Google Cloud Secret Manager via Workload Identity Federation para acesso a segredos consciente de rotação e sem credenciais
|
||||
sidebarTitle: Com Workload Identity
|
||||
icon: "id-badge"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Este guia configura o Google Cloud Secret Manager como provedor de segredos usando **Workload Identity Federation**: a CrewAI Platform emite tokens OIDC de curta duração, os troca por credenciais Google Cloud via Security Token Service e lê seus segredos — sem que uma chave de service account de longa duração seja armazenada em lugar algum.
|
||||
|
||||
<Note>
|
||||
**Por que este caminho:** os segredos são resolvidos no momento de execução da automação, então **valores rotacionados se propagam para o próximo kickoff sem novo deploy**. Se você só precisa de credenciais estáticas, veja o guia mais simples [GCP — chave de service account](/pt-BR/enterprise/features/secrets-manager/gcp).
|
||||
</Note>
|
||||
|
||||
### Como funciona em runtime
|
||||
|
||||
1. O worker do deployment solicita um JWT OIDC fresco à CrewAI Platform.
|
||||
2. O worker troca o JWT por uma credencial Google federada via [Security Token Service](https://cloud.google.com/iam/docs/reference/sts/rest), referenciando o Workload Identity Pool Provider que você configurou abaixo.
|
||||
3. O worker chama `secretmanager.googleapis.com:accessSecretVersion` para ler o segredo, usando a credencial federada diretamente (o principal federado detém `roles/secretmanager.secretAccessor` — veja Passo 4).
|
||||
4. O valor obtido é injetado como valor da variável de ambiente para aquele kickoff de automação.
|
||||
|
||||
Tokens OIDC subject são cacheados por ~1 hora para evitar reemissão a cada kickoff. Valores de segredos são buscados frescos a cada kickoff independentemente do estado do cache OIDC, e é isso que torna este caminho consciente de rotação.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
<Note>
|
||||
Antes de começar, certifique-se de que você tem:
|
||||
|
||||
- A imagem do pod de automação deve incluir o runtime da CrewAI versão `1.14.5` ou superior.
|
||||
- Um projeto Google Cloud com as APIs **Secret Manager**, **Security Token Service** e **IAM Credentials** habilitadas. Habilite-as via console ou:
|
||||
|
||||
```bash
|
||||
gcloud services enable secretmanager.googleapis.com sts.googleapis.com iamcredentials.googleapis.com \
|
||||
--project=<YOUR_PROJECT_ID>
|
||||
```
|
||||
|
||||
- Permissão no projeto para criar Workload Identity Pools, papéis IAM, service accounts e (se necessário) segredos.
|
||||
- Uma organização na CrewAI Platform onde seu usuário tem as permissões `workload_identity_configs: manage` e `secret_providers: manage`. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac).
|
||||
- **Sua instalação da CrewAI Platform deve ser acessível a partir do Google Cloud via HTTPS** para que o GCP STS possa buscar o documento de discovery OIDC e o JWKS durante a validação do token. Confirme com o administrador da sua plataforma que o host é acessível pela internet.
|
||||
</Note>
|
||||
|
||||
## Passo 1 — Encontre a URL do Issuer OIDC da Sua CrewAI Platform
|
||||
|
||||
Sua instalação da CrewAI Platform publica um documento de discovery OpenID Connect em `https://<your-platform-host>/.well-known/openid-configuration`. O campo `issuer` ali é a URL que o Google registrará como provedor OIDC confiável.
|
||||
|
||||
Abra a URL em um navegador:
|
||||
|
||||
```
|
||||
https://<your-platform-host>/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
Você deverá ver um JSON contendo:
|
||||
|
||||
```json
|
||||
{
|
||||
"issuer": "https://<your-platform-host>",
|
||||
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Anote o valor exato de `issuer` — você o usará no Passo 3.
|
||||
|
||||
<Tip>
|
||||
Se a URL retornar 404 ou 503, contate o administrador da sua plataforma. O issuer OIDC requer uma chave de assinatura privada configurada no momento da instalação. Veja o guia de instalação da plataforma para as configurações `OIDC_PRIVATE_KEY` e `OIDC_ISSUER`.
|
||||
</Tip>
|
||||
|
||||
## Passo 2 — Criar um Workload Identity Pool
|
||||
|
||||
Um Workload Identity Pool é um container do lado Google Cloud para identidades externas confiáveis. Você registrará a CrewAI Platform como um provedor dentro desse pool.
|
||||
|
||||
```bash
|
||||
gcloud iam workload-identity-pools create crewai-pool \
|
||||
--project=<YOUR_PROJECT_ID> \
|
||||
--location=global \
|
||||
--display-name="CrewAI Platform"
|
||||
```
|
||||
|
||||
Ou no [console Workload Identity Pools](https://console.cloud.google.com/iam-admin/workload-identity-pools), clique em **Create Pool**.
|
||||
|
||||
{/* SCREENSHOT: GCP "Create Workload Identity Pool" form with name "crewai-pool" → /images/secrets-manager/gcp-wi/01-create-pool.png */}
|
||||
|
||||
## Passo 3 — Adicionar a CrewAI Platform como um Provedor OIDC no Pool
|
||||
|
||||
```bash
|
||||
gcloud iam workload-identity-pools providers create-oidc crewai-provider \
|
||||
--project=<YOUR_PROJECT_ID> \
|
||||
--location=global \
|
||||
--workload-identity-pool=crewai-pool \
|
||||
--display-name="CrewAI Platform OIDC" \
|
||||
--issuer-uri="https://<your-platform-host>" \
|
||||
--attribute-mapping="google.subject=assertion.sub,attribute.organization=assertion.organization_id" \
|
||||
--attribute-condition="assertion.organization_id != ''"
|
||||
```
|
||||
|
||||
O `--attribute-mapping` diz ao Google como mapear claims do JWT para atributos do Google:
|
||||
- `google.subject` é o identificador do principal — mapeamos para a claim `sub` do JWT, que a CrewAI Platform define como `organization:<uuid>`.
|
||||
- `attribute.organization` é um atributo customizado — mapeamos para a claim `organization_id` do JWT para que você possa referenciá-la em vínculos IAM mais tarde.
|
||||
|
||||
O `--attribute-condition` é uma verificação de defesa em profundidade que rejeita tokens sem uma claim `organization_id`.
|
||||
|
||||
Obtenha o **nome do recurso do provedor** (você precisará dele para a audience e vínculos IAM):
|
||||
|
||||
```bash
|
||||
gcloud iam workload-identity-pools providers describe crewai-provider \
|
||||
--project=<YOUR_PROJECT_ID> \
|
||||
--location=global \
|
||||
--workload-identity-pool=crewai-pool \
|
||||
--format="value(name)"
|
||||
```
|
||||
|
||||
A saída se parece com:
|
||||
|
||||
```
|
||||
projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider
|
||||
```
|
||||
|
||||
Este é seu valor de **Workload Identity Provider** para a CrewAI Platform no Passo 6. A CrewAI Platform automaticamente computa a audience OIDC como `//iam.googleapis.com/<this-resource-name>` ao emitir tokens.
|
||||
|
||||
{/* SCREENSHOT: "Add provider to pool" form with OIDC selected, issuer URI, audience defaults, attribute mapping → /images/secrets-manager/gcp-wi/02-add-oidc-provider.png */}
|
||||
|
||||
## Passo 4 — Conceder Acesso ao Secret Manager ao Principal Federado
|
||||
|
||||
Vincule ambos os papéis do Secret Manager no escopo do projeto ao principal federado — um papel habilita o autocomplete de Secret Name no formulário de env-var, o outro permite ler valores de segredos no kickoff da automação. Ambos são necessários para que o recurso funcione de ponta a ponta.
|
||||
|
||||
```bash
|
||||
PRINCIPAL_SET="principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/attribute.organization/<YOUR_CREWAI_ORG_UUID>"
|
||||
|
||||
# Necessário para o autocomplete de Secret Name (chama secretmanager.secrets.list)
|
||||
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
|
||||
--member="$PRINCIPAL_SET" \
|
||||
--role="roles/secretmanager.viewer"
|
||||
|
||||
# Necessário para ler valores de segredos no kickoff
|
||||
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
|
||||
--member="$PRINCIPAL_SET" \
|
||||
--role="roles/secretmanager.secretAccessor"
|
||||
```
|
||||
|
||||
Substitua `<PROJECT_NUMBER>` pelo número numérico do projeto (`gcloud projects describe <YOUR_PROJECT_ID> --format='value(projectNumber)'`) e `<YOUR_CREWAI_ORG_UUID>` pelo UUID da organização CrewAI Platform que deve ter permissão para ler seus segredos. Você pode encontrar o UUID da org na UI da plataforma na página de configurações da organização, ou via API. Isso escopa a federação a uma organização CrewAI específica — apenas tokens emitidos para as automações dessa org são aceitos.
|
||||
|
||||
Ou via console Google Cloud:
|
||||
|
||||
1. Abra **IAM & Admin** → **IAM** do seu projeto.
|
||||
2. Clique em **GRANT ACCESS**.
|
||||
3. **New principals:** cole a string completa `principalSet://...attribute.organization/<YOUR_CREWAI_ORG_UUID>`.
|
||||
4. Atribua o papel **Secret Manager Viewer** (`roles/secretmanager.viewer`).
|
||||
5. Clique em **SAVE**.
|
||||
6. Clique em **GRANT ACCESS** novamente e repita com o papel **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`).
|
||||
|
||||
<Tip>
|
||||
**Isolamento por organização.** O padrão `principalSet://...attribute.organization/<UUID>` restringe o acesso aos tokens de uma organização específica. Se você tiver várias organizações CrewAI compartilhando um projeto Google Cloud, repita ambos os vínculos por organização com o UUID correto — ou use uma condição de atributo menos restritiva se o isolamento não for necessário.
|
||||
</Tip>
|
||||
|
||||
<Tip>
|
||||
**Escopando `secretAccessor` por segredo (opcional).** Se você preferir não conceder `roles/secretmanager.secretAccessor` em nível de projeto, omita o segundo vínculo acima e vincule por segredo:
|
||||
|
||||
```bash
|
||||
gcloud secrets add-iam-policy-binding <SECRET_NAME> \
|
||||
--member="$PRINCIPAL_SET" \
|
||||
--role="roles/secretmanager.secretAccessor" \
|
||||
--project=<YOUR_PROJECT_ID>
|
||||
```
|
||||
|
||||
Mantenha `roles/secretmanager.viewer` no escopo de projeto de qualquer forma — `secretmanager.secrets.list` (do qual o autocomplete depende) não pode ser concedido por segredo.
|
||||
</Tip>
|
||||
|
||||
## Passo 5 — Criar Pelo Menos Um Segredo no GCP
|
||||
|
||||
Se você ainda não tem um segredo para testar, crie um via CLI `gcloud`:
|
||||
|
||||
```bash
|
||||
echo -n "hello from gcp" | gcloud secrets create crewai-test-keyword \
|
||||
--data-file=- \
|
||||
--project=<YOUR_PROJECT_ID> \
|
||||
--replication-policy=automatic
|
||||
```
|
||||
|
||||
Ou via [console Secret Manager](https://console.cloud.google.com/security/secret-manager):
|
||||
|
||||
1. Abra **Secret Manager** no seu projeto GCP.
|
||||
2. Clique em **+ CREATE SECRET**.
|
||||
3. **Name:** `crewai-test-keyword`. **Secret value:** cole seu valor.
|
||||
4. Clique em **CREATE SECRET**.
|
||||
|
||||
## Passo 6 — Adicionar uma Configuração de Workload Identity na CrewAI Platform
|
||||
|
||||
Na CrewAI Platform, navegue até **Settings** → **Workload Identity** e clique em **Add Workload Identity Config**.
|
||||
|
||||
Preencha o formulário:
|
||||
|
||||
- **Name:** Um nome descritivo, ex. `gcp-prod`.
|
||||
- **Cloud Provider:** `GCP`.
|
||||
- **Workload Identity Provider:** o nome do recurso do provedor do Passo 3, ex. `projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider`.
|
||||
- (Opcional) Alterne **Default Configuration** se você quiser que esta seja a config WI padrão selecionada ao criar uma credencial de segredo baseada em GCP.
|
||||
|
||||
Clique em **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Workload Identity Config" form with GCP and provider resource name → /images/secrets-manager/gcp-wi/03-amp-add-wi-config-gcp.png */}
|
||||
{/* SCREENSHOT: Workload Identity list showing both AWS and GCP rows → /images/secrets-manager/gcp-wi/04-amp-wi-list-with-gcp.png */}
|
||||
|
||||
## Passo 7 — Adicionar uma Credencial de Provedor de Segredos Vinculada à Config WI
|
||||
|
||||
Navegue até **Settings** → **Secret Provider Credentials** e clique em **Add Credential**.
|
||||
|
||||
Preencha o formulário:
|
||||
|
||||
- **Name:** Um nome descritivo, ex. `gcp-prod-wi`.
|
||||
- **Provider:** `Google Cloud Secret Manager`.
|
||||
- **Authentication Method:** `Workload Identity`.
|
||||
- **Workload Identity Configuration:** selecione a config que você criou no Passo 6.
|
||||
- **Project ID:** o ID do seu projeto GCP (o mesmo projeto dono dos segredos).
|
||||
- (Opcional) Marque **Set as default credential for this provider**.
|
||||
|
||||
O formulário pedirá apenas o **Project ID** sob Workload Identity — o campo **Service Account JSON** está intencionalmente oculto porque não se aplica a este caminho; a identidade federada vem da config WI vinculada.
|
||||
|
||||
Clique em **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP + Workload Identity + WI config dropdown → /images/secrets-manager/gcp-wi/05-amp-add-credential-gcp-wi.png */}
|
||||
|
||||
## Passo 8 — Testar a Conexão
|
||||
|
||||
Depois de salvar a credencial, clique em **Test Connection**. Para credenciais workload-identity isso verifica o handshake OIDC: a CrewAI Platform emite um JWT e o troca via Security Token Service por um token de acesso Google federado. Um resultado verde significa que o vínculo de federação está saudável.
|
||||
|
||||
Um Test Connection bem-sucedido prova que o Workload Identity Pool, provedor OIDC, mapeamento de atributos e condição de atributo estão todos conectados corretamente. Ele **não** prova que o IAM do Secret Manager está correto — `secretmanager.secrets.list` e `secretmanager.versions.access` são exercitados separadamente quando o autocomplete de Secret Name carrega ou quando uma variável de ambiente é resolvida no kickoff. Veja [Solução de Problemas](#troubleshooting) para modos de falha de handshake.
|
||||
|
||||
## Passo 9 — Referenciar o Segredo em uma Variável de Ambiente
|
||||
|
||||
Referencie o segredo em uma automação, exatamente como você faria para qualquer outra env var apoiada pelo Secrets Manager. Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) para os campos do formulário e o comportamento.
|
||||
|
||||
## Passo 10 — Verificar a Rotação
|
||||
|
||||
Após o deployment estar rodando, rotacione o segredo no GCP adicionando uma nova versão (o Secret Manager sempre lê a versão habilitada mais recente por padrão):
|
||||
|
||||
```bash
|
||||
echo -n "rotated value" | gcloud secrets versions add crewai-test-keyword \
|
||||
--data-file=- \
|
||||
--project=<YOUR_PROJECT_ID>
|
||||
```
|
||||
|
||||
Dispare um novo kickoff de automação. O ambiente do kickoff verá `"rotated value"` — sem novo deploy, sem reinício de worker, sem espera de TTL.
|
||||
|
||||
Para confirmar nos logs do worker, procure por:
|
||||
|
||||
```
|
||||
Workload identity config '<id>' (gcp): N secret(s) resolved
|
||||
```
|
||||
|
||||
Esta linha aparece para cada kickoff e indica uma chamada `accessSecretVersion` fresca contra o GCP.
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
| Sintoma | Causa provável |
|
||||
|---|---|
|
||||
| Test Connection falha com erro de handshake | A troca de tokens STS foi rejeitada. Verifique se o Workload Identity Pool existe, se o issuer do provedor OIDC corresponde ao valor `issuer` da plataforma e se a condição de atributo aceita as claims do JWT. Confirme que a URL de discovery OIDC da plataforma é acessível a partir do GCP pela internet pública. |
|
||||
| `Could not refresh access token: invalid_target` | A claim de audience não corresponde à audience esperada do Workload Identity Provider. A CrewAI Platform define a audience automaticamente; se você a customizou, certifique-se de que corresponde a `//iam.googleapis.com/<provider-resource-name>`. |
|
||||
| `Failed to fetch JWKS from issuer` | O GCP STS não consegue acessar o host da sua CrewAI Platform. Confirme que o host é acessível pela internet e que `/.well-known/openid-configuration` retorna 200. |
|
||||
| `Attribute condition rejected token` | A condição de atributo do provedor OIDC (Passo 3) requer `organization_id`. A CrewAI Platform sempre define essa claim, então isso geralmente significa um pool/provedor mal configurado. Reconfira a condição de atributo do provedor. |
|
||||
| Autocomplete de Secret Name mostra `PERMISSION_DENIED: secretmanager.secrets.list` | O principal federado está sem `roles/secretmanager.viewer` no escopo de projeto. A permissão `secretmanager.secrets.list` é escopada apenas por projeto e não pode ser concedida por segredo. Veja o Passo 4. |
|
||||
| Kickoff falha ao resolver um segredo mesmo que o Test Connection passe | O vínculo WI está saudável, mas `secretmanager.versions.access` está ausente no segredo que falha. Audite `roles/secretmanager.secretAccessor` (escopado por projeto, ou por segredo se você escopou dessa forma no Passo 4). |
|
||||
| Valor rotacionado não é pego no próximo kickoff | Confirme que a env var na automação está referenciando uma credencial baseada em Workload Identity (não uma credencial de chaves estáticas). O caminho estático incorpora valores à imagem do deploy. |
|
||||
|
||||
### Links de Referência
|
||||
|
||||
- GCP: [Workload Identity Federation overview](https://cloud.google.com/iam/docs/workload-identity-federation)
|
||||
- GCP: [Configure Workload Identity Federation with OIDC](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers)
|
||||
- GCP: [Secret Manager IAM roles](https://cloud.google.com/secret-manager/docs/access-control)
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
- [Use segredos em variáveis de ambiente e gerencie permissões](/pt-BR/enterprise/features/secrets-manager/usage)
|
||||
- Para multi-cloud, veja também [AWS Workload Identity (Federação OIDC)](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) e [Azure Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity).
|
||||
189
docs/edge/pt-BR/enterprise/features/secrets-manager/gcp.mdx
Normal file
189
docs/edge/pt-BR/enterprise/features/secrets-manager/gcp.mdx
Normal file
@@ -0,0 +1,189 @@
|
||||
---
|
||||
title: Google Cloud Secret Manager
|
||||
description: Configure o Google Cloud Secret Manager como provedor de segredos para a CrewAI Platform, de ponta a ponta
|
||||
sidebarTitle: Com Credenciais Estáticas
|
||||
icon: "key"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Este guia o orienta na configuração do Google Cloud Secret Manager como provedor de segredos para sua organização na CrewAI Platform, usando **credenciais de service account**. Ao final, a CrewAI Platform poderá ler segredos armazenados no seu projeto Google Cloud e injetá-los como valores de variáveis de ambiente em runtime.
|
||||
|
||||
<Note>
|
||||
Este guia cobre o caminho de **credenciais estáticas** — segredos são resolvidos no momento do deploy e incorporados à imagem do deployment. Valores rotacionados exigem um novo deploy. Se você quiser segredos conscientes de rotação que se atualizam a cada kickoff de automação, veja [GCP Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity).
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Este guia cobre a configuração do lado GCP e a configuração da credencial na CrewAI Platform. Para então referenciar um segredo a partir de uma variável de ambiente, veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage).
|
||||
</Note>
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
<Note>
|
||||
Antes de começar, certifique-se de que você tem:
|
||||
|
||||
- Um projeto Google Cloud com a **Secret Manager API** habilitada. Habilite-a no [console APIs & Services](https://console.cloud.google.com/apis/library/secretmanager.googleapis.com) ou via `gcloud`:
|
||||
|
||||
```bash
|
||||
gcloud services enable secretmanager.googleapis.com --project=YOUR_PROJECT_ID
|
||||
```
|
||||
|
||||
- Permissão no projeto para criar service accounts, conceder papéis IAM e (se necessário) criar segredos.
|
||||
- Uma organização na CrewAI Platform onde seu usuário tem a permissão `secret_providers: manage`. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac).
|
||||
</Note>
|
||||
|
||||
## Passo 1 — Criar uma Service Account
|
||||
|
||||
Uma service account é a identidade do lado GCP como a qual a CrewAI Platform irá se autenticar.
|
||||
|
||||
No [console IAM & Admin → Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts), clique em **Create Service Account**.
|
||||
|
||||
- **Service account name:** `crewai-secrets-reader`
|
||||
- **Service account ID:** preenchido automaticamente a partir do nome (ex. `crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com`)
|
||||
- **Description (optional):** "Read-only access to Secret Manager for CrewAI Platform"
|
||||
|
||||
Clique em **Create and Continue**. Pule as concessões opcionais nesta tela — você anexará o papel no Passo 2. Clique em **Done**.
|
||||
|
||||
Para detalhes completos, veja a documentação GCP: [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create).
|
||||
|
||||
{/* SCREENSHOT: GCP "Create service account" form with name "crewai-secrets-reader" → /images/secrets-manager/gcp/01-create-service-account.png */}
|
||||
|
||||
## Passo 2 — Conceder Acesso ao Secret Manager
|
||||
|
||||
A CrewAI Platform precisa de permissão para listar e ler segredos no seu projeto. Use um de dois escopos — **a nível de projeto** para simplicidade ou **por segredo** para menor privilégio.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="A nível de projeto (mais simples)">
|
||||
No [console IAM](https://console.cloud.google.com/iam-admin/iam), clique em **Grant Access** e:
|
||||
|
||||
- **New principals:** o email da service account do Passo 1.
|
||||
- **Role:** **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`).
|
||||
|
||||
Clique em **Save**.
|
||||
|
||||
Ou via `gcloud`:
|
||||
|
||||
```bash
|
||||
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
|
||||
--member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
|
||||
--role="roles/secretmanager.secretAccessor"
|
||||
```
|
||||
|
||||
{/* SCREENSHOT: GCP IAM "Grant access" panel with the service account and Secret Manager Secret Accessor role → /images/secrets-manager/gcp/02-iam-grant-access.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="Por segredo (menor privilégio)">
|
||||
Conceda o papel apenas nos segredos específicos que a CrewAI Platform deve acessar. Repita para cada segredo:
|
||||
|
||||
```bash
|
||||
gcloud secrets add-iam-policy-binding YOUR_SECRET_NAME \
|
||||
--member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
|
||||
--role="roles/secretmanager.secretAccessor" \
|
||||
--project=YOUR_PROJECT_ID
|
||||
```
|
||||
|
||||
Ou no console: abra cada segredo no [Secret Manager](https://console.cloud.google.com/security/secret-manager), clique em **Permissions** no painel à direita e conceda **Secret Manager Secret Accessor** à service account.
|
||||
|
||||
{/* SCREENSHOT: Per-secret "Permissions" panel in Secret Manager with the service account granted accessor role → /images/secrets-manager/gcp/03-per-secret-permissions.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
O papel `roles/secretmanager.secretAccessor` concede acesso somente leitura aos valores de segredos. A CrewAI Platform também chama `secretmanager.secrets.list` para a experiência de autocomplete no formulário de env-var — essa permissão está incluída no papel no escopo de projeto, mas **não** no escopo por segredo. Com vínculos por segredo, o autocomplete não sugerirá segredos; você precisará digitar o nome completo do segredo.
|
||||
</Tip>
|
||||
|
||||
## Passo 3 — Criar uma Chave de Service Account
|
||||
|
||||
Abra a service account do Passo 1 no [console IAM & Admin → Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts).
|
||||
|
||||
- Clique na aba **Keys**.
|
||||
- Clique em **Add Key** → **Create new key**.
|
||||
- **Key type:** JSON.
|
||||
- Clique em **Create**. O navegador baixa um arquivo JSON — mantenha-o seguro; não pode ser baixado novamente.
|
||||
|
||||
Ou via `gcloud`:
|
||||
|
||||
```bash
|
||||
gcloud iam service-accounts keys create ./crewai-secrets-reader.json \
|
||||
--iam-account=crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com
|
||||
```
|
||||
|
||||
<Warning>
|
||||
A chave de service account é uma credencial estática de longa duração. Armazene-a com segurança (em um gerenciador de senhas ou no seu próprio cofre de segredos) e rotacione-a em uma cadência regular. Para eliminar credenciais estáticas completamente, use [GCP Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity).
|
||||
</Warning>
|
||||
|
||||
{/* SCREENSHOT: Service account "Keys" tab with the "Create new key" → JSON option → /images/secrets-manager/gcp/04-create-service-account-key.png */}
|
||||
|
||||
## Passo 4 — Adicionar a Credencial na CrewAI Platform
|
||||
|
||||
Na CrewAI Platform, navegue até **Settings** → **Secret Provider Credentials** e clique em **Add Credential**.
|
||||
|
||||
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
|
||||
|
||||
Preencha o formulário:
|
||||
|
||||
- **Name:** Um nome descritivo, ex. `gcp-prod`.
|
||||
- **Provider:** `Google Cloud Secret Manager`.
|
||||
- **Project ID:** O ID do seu projeto GCP (ex. `my-crewai-prod`).
|
||||
- **Service Account JSON:** Cole o conteúdo inteiro do arquivo JSON que você baixou no Passo 3.
|
||||
- (Opcional) Marque **Set as default credential for this provider**. A credencial padrão é usada por variáveis de ambiente que referenciam segredos GCP sem especificar uma credencial explicitamente.
|
||||
|
||||
Clique em **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP fields filled in → /images/secrets-manager/gcp/05-amp-add-credential-form-gcp.png */}
|
||||
|
||||
## Passo 5 — Criar Pelo Menos Um Segredo no GCP
|
||||
|
||||
Se você ainda não tem segredos no GCP Secret Manager, crie um agora para que possa verificar a conexão no Passo 6.
|
||||
|
||||
No [console Secret Manager](https://console.cloud.google.com/security/secret-manager), clique em **Create secret**.
|
||||
|
||||
- **Name:** Um nome único, ex. `openai-api-key`.
|
||||
- **Secret value:** Cole um valor bruto ou faça upload de um arquivo.
|
||||
- Deixe as configurações de rotação, replicação e outras em seus padrões a menos que tenha um requisito específico.
|
||||
|
||||
Clique em **Create secret**.
|
||||
|
||||
Ou via `gcloud`:
|
||||
|
||||
```bash
|
||||
echo -n "sk-your-actual-key" | gcloud secrets create openai-api-key \
|
||||
--data-file=- \
|
||||
--project=YOUR_PROJECT_ID \
|
||||
--replication-policy=automatic
|
||||
```
|
||||
|
||||
<Note>
|
||||
**Sintaxe de referência por chave JSON.** O GCP Secret Manager trata valores de segredos como blobs opacos. Se o valor do seu segredo for uma string JSON, a CrewAI Platform pode extrair um único campo usando a sintaxe `secret-name#json_key` (ex. `database-credentials#password`). Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) para detalhes.
|
||||
</Note>
|
||||
|
||||
Para detalhes completos, veja a documentação GCP: [Create a secret](https://cloud.google.com/secret-manager/docs/create-secret-quickstart).
|
||||
|
||||
{/* SCREENSHOT: GCP "Create secret" form with name and value → /images/secrets-manager/gcp/06-create-secret.png */}
|
||||
|
||||
## Passo 6 — Testar a Conexão
|
||||
|
||||
De volta à CrewAI Platform, na página **Secret Provider Credentials**, encontre a credencial que você acabou de criar e clique em **Test Connection**.
|
||||
|
||||
Um toast de sucesso confirma que a CrewAI Platform consegue se autenticar no GCP e ler segredos do seu projeto.
|
||||
|
||||
{/* SCREENSHOT: Success toast after clicking "Test Connection" on the GCP credential → /images/secrets-manager/gcp/07-test-connection-success.png */}
|
||||
|
||||
Se o teste falhar, verifique as causas mais comuns:
|
||||
|
||||
| Sintoma | Causa provável |
|
||||
|---|---|
|
||||
| `PERMISSION_DENIED` ao listar segredos | A service account está sem `roles/secretmanager.secretAccessor`, ou você escopou por segredo (`list` não é concedido). Reconfira o Passo 2. |
|
||||
| `PERMISSION_DENIED` em `secretmanager.secrets.access` | Mesmo que acima, mas para um segredo específico. Confirme que a service account tem o papel accessor no segredo em questão. |
|
||||
| `unauthorized_client` / `invalid_grant` | O JSON de Service Account colado é inválido, expirado ou pertence a uma service account excluída. Recrie a chave (Passo 3) e cole novamente. |
|
||||
| `Project ID does not match` | O campo Project ID na CrewAI Platform não corresponde ao projeto dono da service account / segredos. Reconfira o Passo 4. |
|
||||
| `API not enabled` | Secret Manager API não está habilitada no projeto. Veja Pré-requisitos. |
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
Agora que o GCP está conectado, vá para [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage) para:
|
||||
|
||||
- Conceder aos membros da organização as permissões corretas para usar (ou gerenciar) o Secrets Manager.
|
||||
- Referenciar seus segredos GCP a partir de variáveis de ambiente da CrewAI Platform.
|
||||
|
||||
Se você quiser segredos **conscientes de rotação** que se propagam sem novo deploy, mude para [GCP Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity) — mesmo cofre de segredos, sem credenciais estáticas, segredos buscados por kickoff.
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: Visão Geral do Secrets Manager
|
||||
description: Conecte cofres de segredos externos à CrewAI Platform e referencie segredos gerenciados a partir de variáveis de ambiente
|
||||
sidebarTitle: Visão Geral
|
||||
icon: "book-open"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O recurso Secrets Manager permite que sua organização conecte um cofre de segredos externo — AWS Secrets Manager, Google Cloud Secret Manager ou Azure Key Vault — e referencie esses segredos diretamente a partir de variáveis de ambiente nas suas automações e crews. Em vez de colar valores em texto puro na plataforma, você armazena um conjunto de credenciais por provedor e se refere aos segredos pelo nome.
|
||||
|
||||
Isso oferece a você:
|
||||
|
||||
- **Armazenamento centralizado** — gerencie segredos no seu provedor em vez de editar a configuração da CrewAI Platform. A CrewAI Platform não mantém nenhuma cópia em texto puro do valor do segredo.
|
||||
- **Exposição reduzida** — valores sensíveis nunca ficam em texto puro na sua configuração da CrewAI Platform.
|
||||
- **Auditabilidade cloud-native** — o log de auditoria do seu provedor registra cada leitura de segredo.
|
||||
|
||||
<Note>
|
||||
O Secrets Manager (tanto o caminho de credenciais estáticas quanto o de Workload Identity) requer o runtime da CrewAI versão `1.14.5` ou superior na imagem do pod de automação.
|
||||
</Note>
|
||||
|
||||
## Dois Caminhos: Credenciais Estáticas vs Workload Identity
|
||||
|
||||
Existem duas formas de conectar a CrewAI Platform ao cofre de segredos da sua nuvem. **Eles diferem significativamente no comportamento de rotação**, então escolha com base em quão frequentemente seus segredos são rotacionados e quão rigorosa é a sua postura de segurança.
|
||||
|
||||
| Aspecto | Credenciais Estáticas | Workload Identity (Federação OIDC) |
|
||||
|---|---|---|
|
||||
| **Autenticação** | Chaves de acesso de longa duração / JSON de service account armazenados na CrewAI Platform | Tokens de curta duração emitidos por processo worker; nenhuma credencial estática armazenada em lugar algum |
|
||||
| **Propagação de rotação** | Resolvida no momento do deploy e **incorporada à imagem do contêiner do deployment** — valores rotacionados exigem um novo deploy | Resolvida no **momento da execução da automação** — valores rotacionados se propagam para o próximo kickoff sem novo deploy |
|
||||
| **Esforço de configuração** | Menor — cole chaves / faça upload do JSON da service account | Maior — registre a CrewAI Platform como um provedor OIDC na sua nuvem, configure políticas de confiança |
|
||||
| **Melhor para** | Começar rápido, segredos rotacionados raramente, deployments single-account | Produção, segredos rotacionados frequentemente, ambientes guiados por compliance que proíbem credenciais de longa duração |
|
||||
|
||||
<Note>
|
||||
**Ambos os caminhos usam o mesmo fluxo de UI** para referenciar segredos em variáveis de ambiente (veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage)). A diferença está inteiramente em como a plataforma se autentica na sua nuvem e em quando lê o valor do segredo.
|
||||
</Note>
|
||||
|
||||
### Escolha seu guia de configuração
|
||||
|
||||
| Provedor | Credenciais Estáticas | Workload Identity |
|
||||
|---|---|---|
|
||||
| AWS Secrets Manager | [AWS — chaves estáticas / AssumeRole](/pt-BR/enterprise/features/secrets-manager/aws) | [AWS — Workload Identity (OIDC)](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) |
|
||||
| Google Cloud Secret Manager | [GCP — chave de service account](/pt-BR/enterprise/features/secrets-manager/gcp) | [GCP — Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity) |
|
||||
| Azure Key Vault | [Azure — client secret](/pt-BR/enterprise/features/secrets-manager/azure) | [Azure — Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity) |
|
||||
|
||||
<Note>
|
||||
As interfaces de Secrets Manager e Workload Identity estão atualmente marcadas como **Beta** na CrewAI Platform.
|
||||
</Note>
|
||||
|
||||
## Como Tudo se Encaixa
|
||||
|
||||
Configurar o Secrets Manager é um fluxo de três passos que envolve tanto o seu provedor de nuvem quanto a CrewAI Platform:
|
||||
|
||||
1. **Um admin configura uma credencial de provedor.** Este é o trabalho do lado da nuvem — e o trabalho difere dependendo de qual caminho (credenciais estáticas ou Workload Identity) você escolher. Os guias específicos por provedor cobrem isso de ponta a ponta.
|
||||
2. **Um admin (ou um membro autorizado) referencia um segredo em uma variável de ambiente.** Na página de Variáveis de Ambiente, o usuário escolhe uma credencial de provedor e seleciona o nome do segredo. Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables).
|
||||
3. **A automação recebe o valor resolvido em runtime.** Quando um crew ou automação executa, a CrewAI Platform busca o segredo do seu provedor e o injeta como o valor da variável de ambiente. Com Workload Identity, essa busca acontece a cada kickoff (consciente de rotação). Com credenciais estáticas, essa busca acontece no momento do deploy e o valor é incorporado à imagem do deployment.
|
||||
|
||||
## Visibilidade & Escopo
|
||||
|
||||
<Note>
|
||||
Variáveis de ambiente atreladas a WI seguem o mesmo modelo de atribuição das variáveis de ambiente em texto puro: uma automação resolve apenas as variáveis atreladas a WI explicitamente atribuídas a ela. Atribua uma variável atrelada a WI a uma automação pela página de Variáveis de Ambiente dessa automação; variáveis definidas no nível da organização ou em um projeto Studio não são resolvidas em kickoff até que você as atribua.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
A fase de busca de segredos é executada em todo kickoff, mas só realiza trabalho quando há variáveis de ambiente atreladas a WI atribuídas ao deployment. Para cada variável atribuída, o runtime resolve o valor a partir do seu provedor de nuvem em todo kickoff de crew, flow, training, test ou checkpoint-restore e o grava no ambiente do processo. Sem nada atribuído, a fase é um no-op. Caso contrário, o custo é proporcional ao número de variáveis atribuídas: uma pequena latência adicional por kickoff mais uma entrada no audit log do lado da nuvem por variável.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
No nível das *configurações* de Workload Identity, o escopo ainda é abrangente a toda a organização hoje. Toda automação na organização é inicializada com base em todas as configurações de Workload Identity que a organização registrou, e hoje você não pode vincular uma configuração específica de Workload Identity a uma automação específica. Escopo por automação para Workload Identity está no roadmap. Até lá, registre apenas configurações de Workload Identity que toda automação da sua organização tenha permissão de usar.
|
||||
</Warning>
|
||||
|
||||
## Permissões
|
||||
|
||||
Duas features da CrewAI Platform controlam o acesso ao Secrets Manager:
|
||||
|
||||
- `secret_providers` — controla quem pode visualizar ou gerenciar credenciais de provedor.
|
||||
- `environment_variables` — controla quem pode criar e editar variáveis de ambiente (incluindo aquelas que referenciam segredos).
|
||||
|
||||
Uma terceira feature controla a configuração do Workload Identity:
|
||||
|
||||
- `workload_identity_configs` — controla quem pode visualizar ou gerenciar configurações de Workload Identity. Necessário apenas se você estiver usando o caminho Workload Identity.
|
||||
|
||||
Owners sempre têm acesso total. Members **não** recebem acesso a `secret_providers` ou `workload_identity_configs` por padrão e precisam receber permissão por meio de um papel customizado. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac) para a matriz completa e instruções passo a passo.
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
Escolha seu caminho:
|
||||
|
||||
- **Credenciais estáticas** (mais simples, requer novo deploy na rotação):
|
||||
- [Configurar AWS Secrets Manager](/pt-BR/enterprise/features/secrets-manager/aws)
|
||||
- [Configurar Google Cloud Secret Manager](/pt-BR/enterprise/features/secrets-manager/gcp)
|
||||
- [Configurar Azure Key Vault](/pt-BR/enterprise/features/secrets-manager/azure)
|
||||
- **Workload Identity** (consciente de rotação, sem novo deploy):
|
||||
- [Configurar AWS Workload Identity](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity)
|
||||
- [Configurar GCP Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity)
|
||||
- [Configurar Azure Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity)
|
||||
- Em seguida: [Use segredos em variáveis de ambiente e gerencie permissões](/pt-BR/enterprise/features/secrets-manager/usage)
|
||||
137
docs/edge/pt-BR/enterprise/features/secrets-manager/usage.mdx
Normal file
137
docs/edge/pt-BR/enterprise/features/secrets-manager/usage.mdx
Normal file
@@ -0,0 +1,137 @@
|
||||
---
|
||||
title: Usando o Secrets Manager
|
||||
description: Gerencie permissões e referencie segredos gerenciados a partir de variáveis de ambiente na CrewAI Platform
|
||||
sidebarTitle: Uso e Permissões
|
||||
icon: "list-check"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Este guia é agnóstico em relação ao provedor. Ele assume que você (ou outro admin) já configurou pelo menos uma Credencial de Provedor de Segredos. Escolha seu guia de configuração com base no caminho que deseja:
|
||||
|
||||
- Credenciais estáticas: [AWS](/pt-BR/enterprise/features/secrets-manager/aws) · [GCP](/pt-BR/enterprise/features/secrets-manager/gcp)
|
||||
- Workload Identity (consciente de rotação): [AWS](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity)
|
||||
|
||||
Use este guia para:
|
||||
|
||||
- Conceder as permissões corretas aos membros da organização.
|
||||
- Referenciar segredos a partir de variáveis de ambiente nas suas automações.
|
||||
- Verificar se tudo é resolvido corretamente em runtime.
|
||||
|
||||
## Permissões (RBAC)
|
||||
|
||||
Três features da CrewAI Platform são relevantes ao trabalhar com o Secrets Manager:
|
||||
|
||||
- `secret_providers` — controla o acesso à página **Secret Provider Credentials**.
|
||||
- `workload_identity_configs` — controla o acesso à página **Workload Identity** (relevante apenas se você usar o caminho WI).
|
||||
- `environment_variables` — controla quem pode criar ou editar variáveis de ambiente.
|
||||
|
||||
Cada feature tem dois níveis de ação: `read` e `manage`. Conceder `manage` implica automaticamente em `read`.
|
||||
|
||||
### O que Conceder
|
||||
|
||||
| Objetivo | `secret_providers` | `workload_identity_configs` | `environment_variables` |
|
||||
|---|---|---|---|
|
||||
| Usar credenciais estáticas existentes em variáveis de ambiente (sem edição de provedor) | `read` | — | `manage` |
|
||||
| Criar, editar ou excluir credenciais estáticas | `manage` | — | `manage` |
|
||||
| Usar credenciais existentes baseadas em Workload Identity em env vars | `read` | — | `manage` |
|
||||
| Criar, editar ou excluir configs de Workload Identity (e credenciais que as referenciam) | `manage` | `manage` | `manage` |
|
||||
|
||||
<Note>
|
||||
**Owners** automaticamente têm acesso total a todas as features. O papel padrão **Member** intencionalmente exclui `secret_providers` e `workload_identity_configs` — admins devem incluir explicitamente os membros por meio de um papel customizado.
|
||||
</Note>
|
||||
|
||||
### Como Atribuir
|
||||
|
||||
1. Na CrewAI Platform, navegue até **Settings** → **Roles**. Nesta página você pode criar novos papéis, editar as permissões de cada papel e atribuir papéis aos membros existentes da organização.
|
||||
|
||||
{/* SCREENSHOT: Sidebar highlighting Settings → Roles → /images/secrets-manager/usage/06-amp-settings-roles-nav.png */}
|
||||
{/* SCREENSHOT: Roles list page with "Create Role" button visible → /images/secrets-manager/usage/07-amp-roles-list.png */}
|
||||
|
||||
2. Clique em **Create Role** para criar um novo papel ou abra um papel existente para editar suas permissões.
|
||||
|
||||
3. No editor de permissões do papel, alterne as features relevantes conforme a tabela acima:
|
||||
|
||||
- `secret_providers`: escolha **read** se este papel só precisa usar credenciais existentes, ou **manage** se também deve ser capaz de criar, editar e excluir credenciais.
|
||||
- `environment_variables`: escolha **manage** para que o papel possa criar variáveis de ambiente que referenciam segredos.
|
||||
|
||||
{/* SCREENSHOT: Role editor showing the secret_providers feature with read/manage toggles → /images/secrets-manager/usage/08-amp-role-editor-secret-providers-toggles.png */}
|
||||
{/* SCREENSHOT: Role editor showing environment_variables toggles → /images/secrets-manager/usage/09-amp-role-editor-env-vars-toggles.png */}
|
||||
|
||||
4. Salve o papel.
|
||||
|
||||
5. Atribua o papel aos membros relevantes pela mesma página de Roles (ou pela lista de Membros da organização).
|
||||
|
||||
{/* SCREENSHOT: Member assignment screen where the new role is applied to a user → /images/secrets-manager/usage/10-amp-assign-role-to-member.png */}
|
||||
|
||||
## Referenciando Segredos em Variáveis de Ambiente
|
||||
|
||||
Uma vez que uma credencial de provedor exista e seu papel tenha as permissões corretas, você pode referenciar segredos gerenciados a partir de qualquer variável de ambiente.
|
||||
|
||||
Na CrewAI Platform, navegue até **Environment Variables** e clique em **Add Environment Variables**.
|
||||
|
||||
{/* SCREENSHOT: Environment Variables empty state with "Add" button → /images/secrets-manager/usage/11-amp-env-vars-empty.png */}
|
||||
|
||||
Preencha o formulário:
|
||||
|
||||
- **Key** — o nome da variável de ambiente. Deve começar com uma letra ou underscore e conter apenas letras, números e underscores. Convencionalmente em maiúsculas, ex. `OPENAI_API_KEY`.
|
||||
|
||||
- **Value Source** — escolha de onde vem o valor:
|
||||
- **Direct Value** — um valor em texto puro que você digita. Use isto quando não quiser envolver um provedor.
|
||||
- **Use AWS default** (ou o equivalente para o seu provedor) — usa a credencial atualmente marcada como padrão para aquele tipo de provedor.
|
||||
- **A specific named credential** — selecione a credencial pelo nome. Use isto se você tiver múltiplas credenciais para o mesmo provedor (por exemplo, `aws-prod` e `aws-staging`) e quiser escolher uma explicitamente.
|
||||
|
||||
{/* SCREENSHOT: Env var form with the "Value Source" dropdown open, showing "AWS default" + named credentials → /images/secrets-manager/usage/12-amp-env-var-form-source-selector.png */}
|
||||
|
||||
- **Secret Name** — o nome do segredo no seu provedor. Uma vez que uma credencial é selecionada, este campo oferece autocomplete: comece a digitar e a CrewAI Platform consulta seu provedor por nomes de segredos correspondentes.
|
||||
|
||||
Use a sintaxe `secret-name#json_key` para extrair um único campo de um segredo estruturado (JSON). Por exemplo, dado um segredo `database-credentials` com valor `{"username": "...", "password": "..."}`, referencie `database-credentials#password` para injetar apenas a senha.
|
||||
|
||||
{/* SCREENSHOT: Env var form with the secret name autocomplete dropdown showing live results → /images/secrets-manager/usage/13-amp-env-var-form-secret-name-autocomplete.png */}
|
||||
|
||||
<Note>
|
||||
**Nota sobre Azure Key Vault:** Nomes de segredos do Azure não podem conter underscores. A CrewAI Platform converte automaticamente underscores no seu campo `Secret Name` para hífens ao chamar o Azure (ex.: `db_password` é enviado como `db-password`).
|
||||
</Note>
|
||||
|
||||
Clique em **Create** para salvar a variável.
|
||||
|
||||
{/* SCREENSHOT: Env var list with the new variable showing masked value and a "secret" indicator → /images/secrets-manager/usage/14-amp-env-var-created.png */}
|
||||
|
||||
<Tip>
|
||||
Ao editar uma variável de ambiente existente, deixar o campo **Value** em branco preserva o valor atual. Isto é intencional — permite que você altere outros campos (como o nome do segredo ou a credencial) sem precisar digitar o valor novamente.
|
||||
</Tip>
|
||||
|
||||
## Verificando se Funciona
|
||||
|
||||
Para verificar de ponta a ponta:
|
||||
|
||||
1. Referencie a variável de ambiente em uma automação, crew ou deployment exatamente como você faria com qualquer outra variável de ambiente.
|
||||
2. Faça o deploy da automação.
|
||||
3. Dispare uma execução e confirme que ela é concluída com sucesso.
|
||||
|
||||
### O comportamento de rotação depende do caminho da credencial
|
||||
|
||||
| Caminho da credencial | Quando o segredo é lido | O que a rotação requer |
|
||||
|---|---|---|
|
||||
| **Credenciais estáticas** (chaves de acesso AWS, JSON de service account GCP) | No **momento do deploy** — o valor é incorporado à imagem do deployment | Fazer novo deploy da automação após rotacionar o segredo |
|
||||
| **Workload Identity** (federação OIDC, AWS ou GCP) | A **cada kickoff de automação** — o valor é buscado de forma fresca da sua nuvem | Nada — o próximo kickoff após a rotação verá o novo valor |
|
||||
|
||||
<Note>
|
||||
**Se você precisa de segredos conscientes de rotação** (sem novo deploy na rotação), use o caminho Workload Identity: [AWS WI](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) ou [GCP WI](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity). O trade-off é mais esforço de configuração inicial (registrar a CrewAI Platform como provedor OIDC na sua nuvem), mas operações mais simples no longo prazo.
|
||||
</Note>
|
||||
|
||||
Se o deploy ou a execução falhar com um erro relacionado ao seu segredo, verifique as causas mais comuns:
|
||||
|
||||
| Sintoma | Causa provável |
|
||||
|---|---|
|
||||
| `no credential found` | A variável de ambiente referencia um provedor, mas nenhuma credencial específica foi selecionada e não há credencial padrão definida para aquele tipo de provedor. Selecione uma credencial explicitamente na variável, ou marque uma credencial como padrão na página **Secret Provider Credentials**. |
|
||||
| `secret not found` | Erro de digitação no **Secret Name**, ou o segredo não existe na conta/região do provedor para a qual a credencial aponta. Reconfira ambos. |
|
||||
| Automação executa com o valor antigo após rotação (caminho de credenciais estáticas) | O valor anterior está incorporado à imagem do contêiner do deployment. Faça novo deploy da automação para pegar o valor rotacionado. Para evitar isso completamente, mude a credencial para o caminho Workload Identity. |
|
||||
| Automação executa com o valor antigo após rotação (caminho Workload Identity) | Confirme que a env var referencia uma credencial baseada em WI (não uma de chaves estáticas). Com WI, o próximo kickoff após a rotação deve ver o novo valor. Se não vir, verifique se o segredo foi realmente atualizado na sua nuvem (ex.: `aws secretsmanager get-secret-value`). |
|
||||
| `JSON key not found` | Ao usar `secret-name#json_key`, o segredo subjacente deve ser um objeto JSON válido contendo essa chave. Verifique lendo o segredo diretamente no seu provedor. |
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
- [Voltar à visão geral do Secrets Manager](/pt-BR/enterprise/features/secrets-manager/overview)
|
||||
- Credenciais estáticas: [AWS](/pt-BR/enterprise/features/secrets-manager/aws) · [GCP](/pt-BR/enterprise/features/secrets-manager/gcp)
|
||||
- Workload Identity (consciente de rotação): [AWS](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity)
|
||||
@@ -0,0 +1,261 @@
|
||||
---
|
||||
title: Verificar Rotação
|
||||
description: Um crew de exemplo autocontido que prova que a rotação de segredos se propaga para deployments em execução sem novo deploy.
|
||||
sidebarTitle: Verificar Rotação
|
||||
icon: "arrows-rotate"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Este guia mostra como verificar que **um segredo rotacionado no seu provedor de nuvem é pego no próprio kickoff de automação seguinte** — sem novo deploy, sem reinício de worker. É relevante apenas quando você configurou uma credencial baseada em Workload Identity ([AWS](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity)). Deployments com credenciais estáticas exigem um novo deploy após a rotação; nada a verificar aqui.
|
||||
|
||||
A receita abaixo usa um crew minúsculo e autocontido com uma ferramenta, um agente, uma tarefa. O prompt do crew nunca referencia o valor do segredo — em vez disso, uma ferramenta o lê de `os.environ` e reporta um fingerprint SHA-256 do que ela vê. Rotacione o segredo no seu provedor de nuvem, dispare novamente e o fingerprint muda.
|
||||
|
||||
<Note>
|
||||
Por que um fingerprint, não o valor bruto? Colocar segredos brutos na saída do LLM e em trace logs é um vetor de vazamento. O fingerprint é suficiente para confirmar "o valor mudou" sem escrever o valor real em nenhum lugar observável.
|
||||
</Note>
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
Antes de executar esta verificação:
|
||||
|
||||
- Uma Secret Provider Credential baseada em WI está configurada ([AWS](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity)).
|
||||
- Uma variável de ambiente no seu deployment com `Secret = true`, chave `API_KEY` (ou qualquer nome que preferir — ajuste a ferramenta abaixo para corresponder), referenciando um segredo no seu provedor de nuvem.
|
||||
- Uma forma de atualizar o valor do segredo no seu provedor de nuvem (acesso à CLI ou ao console da nuvem).
|
||||
- Uma forma de disparar o deployment via HTTP (curl, Postman ou a aba **Run** na CrewAI Platform).
|
||||
|
||||
## Passo 1 — Estruturar um Crew de Verificação
|
||||
|
||||
Crie um projeto de crew clássico porque este exemplo conecta uma ferramenta Python via `crew.py`:
|
||||
|
||||
```bash
|
||||
crewai create crew rotation_verifier --classic --skip_provider
|
||||
cd rotation_verifier
|
||||
```
|
||||
|
||||
## Passo 2 — Adicionar a Ferramenta de Echo de Credencial
|
||||
|
||||
Substitua `src/rotation_verifier/tools/custom_tool.py` por uma ferramenta que lê a env var apoiada pelo segredo e retorna um fingerprint:
|
||||
|
||||
```python src/rotation_verifier/tools/credential_echo_tool.py
|
||||
"""Tool that verifies a runtime-injected secret without leaking the value.
|
||||
|
||||
Reads the secret-backed env var (populated by the workload-identity
|
||||
secrets manager at kickoff time) and returns a stable fingerprint. Never
|
||||
echo raw credential values into LLM output or logs in production code —
|
||||
the fingerprint alone is sufficient to confirm rotation worked.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import os
|
||||
|
||||
from crewai.tools import BaseTool
|
||||
|
||||
|
||||
# Match the deployment environment variable's `key` field.
|
||||
ENV_VAR_NAME = "API_KEY"
|
||||
|
||||
|
||||
class CredentialEchoTool(BaseTool):
|
||||
name: str = "credential_echo"
|
||||
description: str = (
|
||||
"Read the API credential from the worker's environment and return a "
|
||||
"fingerprint summary. Use this exactly once when asked to verify the "
|
||||
"current credential. Takes no arguments."
|
||||
)
|
||||
|
||||
def _run(self) -> str:
|
||||
value = os.environ.get(ENV_VAR_NAME)
|
||||
if not value:
|
||||
return (
|
||||
f"ERROR: {ENV_VAR_NAME} env var is not set. The workload-"
|
||||
"identity secret fetch did not run, or the deployment is "
|
||||
"missing the secret-backed env var."
|
||||
)
|
||||
fingerprint = hashlib.sha256(value.encode()).hexdigest()[:12]
|
||||
return f"Authenticated. credential.fingerprint=sha256:{fingerprint}"
|
||||
```
|
||||
|
||||
## Passo 3 — Substituir as Configs Padrão de Agente e Task
|
||||
|
||||
O crew tem um agente e uma tarefa — ambos com descrições que **nunca** mencionam o valor do segredo, para que as chaves de tarefa permaneçam estáveis entre rotações.
|
||||
|
||||
```yaml src/rotation_verifier/config/agents.yaml
|
||||
credential_checker:
|
||||
role: >
|
||||
Credential Verifier
|
||||
goal: >
|
||||
Confirm that the workload-identity-backed secret reached this worker
|
||||
process and report a fingerprint of the current value.
|
||||
backstory: >
|
||||
You are a no-nonsense reliability engineer responsible for verifying
|
||||
that secrets fetched at runtime via workload identity are present
|
||||
and fresh. You always use the credential_echo tool exactly once and
|
||||
report the result verbatim — you never make up values.
|
||||
```
|
||||
|
||||
```yaml src/rotation_verifier/config/tasks.yaml
|
||||
verify_credential_task:
|
||||
description: >
|
||||
Use the credential_echo tool to read the runtime-injected credential
|
||||
and produce a one-line confirmation. The current year is {current_year}
|
||||
(use it only in the timestamp; do not transform the credential output).
|
||||
expected_output: >
|
||||
A single line in the form:
|
||||
"[{current_year}] <credential_echo tool's exact output>"
|
||||
agent: credential_checker
|
||||
```
|
||||
|
||||
## Passo 4 — Conectar a Classe do Crew
|
||||
|
||||
```python src/rotation_verifier/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 rotation_verifier.tools.credential_echo_tool import CredentialEchoTool
|
||||
|
||||
|
||||
@CrewBase
|
||||
class RotationVerifierCrew():
|
||||
"""Single-task crew that verifies a workload-identity-backed secret
|
||||
was successfully fetched at runtime.
|
||||
|
||||
Rotate the underlying secret in the cloud provider, kickoff again, and
|
||||
the credential fingerprint in the agent's report changes — without any
|
||||
re-deploy, worker restart, or input change. The crew prompt itself
|
||||
never references the secret value.
|
||||
"""
|
||||
|
||||
agents: list[BaseAgent]
|
||||
tasks: list[Task]
|
||||
|
||||
@agent
|
||||
def credential_checker(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config["credential_checker"],
|
||||
tools=[CredentialEchoTool()],
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
@task
|
||||
def verify_credential_task(self) -> Task:
|
||||
return Task(config=self.tasks_config["verify_credential_task"])
|
||||
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
verbose=True,
|
||||
)
|
||||
```
|
||||
|
||||
## Passo 5 — Fazer Deploy e Configurar a Env Var do Segredo
|
||||
|
||||
Faça deploy deste crew na CrewAI Platform exatamente como você faria com qualquer outro crew. Em seguida, na página **Environment Variables** do deployment:
|
||||
|
||||
- **Key:** `API_KEY` (deve corresponder a `ENV_VAR_NAME` na ferramenta)
|
||||
- **Value Source:** a credencial baseada em WI que você configurou em [AWS WI](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) ou [GCP WI](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity)
|
||||
- **Secret Name:** o nome do segredo no Secret Manager do seu provedor de nuvem
|
||||
|
||||
{/* SCREENSHOT: Environment Variables form with key=API_KEY, secret-backed value source selected, secret name filled → /images/secrets-manager/verify-rotation/01-env-var-form.png */}
|
||||
|
||||
## Passo 6 — Executar o Primeiro Kickoff
|
||||
|
||||
Substitua `<DEPLOYMENT_AUTH_TOKEN>` e `<DEPLOYMENT_HOST>` por valores da aba **Run** do seu deployment.
|
||||
|
||||
```bash
|
||||
curl -m 60 \
|
||||
-H "Authorization: Bearer <DEPLOYMENT_AUTH_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-X POST https://<DEPLOYMENT_HOST>/kickoff \
|
||||
-d '{"inputs":{"current_year":"2026"}}'
|
||||
```
|
||||
|
||||
Quando o kickoff for concluído (alguns segundos), verifique a saída do agente. Você verá:
|
||||
|
||||
```
|
||||
[2026] Authenticated. credential.fingerprint=sha256:004421b993c9
|
||||
```
|
||||
|
||||
Anote o fingerprint. Esse hash está unicamente vinculado a qualquer valor de segredo que esteja atualmente no seu provedor de nuvem.
|
||||
|
||||
## Passo 7 — Rotacionar o Segredo no Seu Provedor de Nuvem
|
||||
|
||||
<Tabs>
|
||||
<Tab title="AWS">
|
||||
```bash
|
||||
aws secretsmanager update-secret \
|
||||
--region <REGION> \
|
||||
--secret-id <SECRET_NAME> \
|
||||
--secret-string "rotated value"
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="GCP">
|
||||
Adicione uma nova versão (o Secret Manager sempre lê `latest`):
|
||||
|
||||
```bash
|
||||
echo -n "rotated value" | gcloud secrets versions add <SECRET_NAME> \
|
||||
--data-file=- \
|
||||
--project=<YOUR_PROJECT_ID>
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Azure">
|
||||
```bash
|
||||
az keyvault secret set \
|
||||
--vault-name <VAULT_NAME> \
|
||||
--name <SECRET_NAME> \
|
||||
--value "rotated value"
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Passo 8 — Executar um Segundo Kickoff e Comparar
|
||||
|
||||
```bash
|
||||
curl -m 60 \
|
||||
-H "Authorization: Bearer <DEPLOYMENT_AUTH_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-X POST https://<DEPLOYMENT_HOST>/kickoff \
|
||||
-d '{"inputs":{"current_year":"2026"}}'
|
||||
```
|
||||
|
||||
A saída do agente agora mostra um **fingerprint diferente**:
|
||||
|
||||
```
|
||||
[2026] Authenticated. credential.fingerprint=sha256:e2fc89848f72
|
||||
```
|
||||
|
||||
Isso prova que a rotação foi pega pelo deployment em execução sem novo deploy, reinício de worker ou outra ação do operador.
|
||||
|
||||
## O que Isso Verifica — e o que Não Verifica
|
||||
|
||||
**Verifica:**
|
||||
- A emissão de tokens OIDC do WI a partir da CrewAI Platform funciona.
|
||||
- A confiança do lado da nuvem (provedor IAM OIDC para AWS, Workload Identity Pool para GCP, Federated Identity Credential para Azure) aceita o token.
|
||||
- A identidade do lado da nuvem (IAM Role / GCP service account / Entra App Registration) tem acesso para ler o segredo.
|
||||
- O valor do segredo chega ao `os.environ` do processo worker no momento do kickoff.
|
||||
- Rotações subsequentes se propagam para o próximo kickoff.
|
||||
|
||||
**Não verifica:**
|
||||
- Que seus crews de produção reais lidam com a rotação graciosamente — ex., tarefas de longa duração que leem a env var uma vez na inicialização continuarão usando o valor antigo até que a tarefa termine. Planeje conforme: leia segredos no ponto de uso, não no momento do import do módulo.
|
||||
|
||||
## Por que Não Referenciar o Segredo Diretamente no Prompt?
|
||||
|
||||
Uma demonstração de aparência mais simples colocaria o valor do segredo diretamente em uma descrição de tarefa (ex.: "Research about `{api_key}`") e inspecionaria o prompt. **Não faça isso.** Duas razões:
|
||||
|
||||
1. **Isso vaza o segredo para traces de chamadas LLM e logs do lado do provedor.** Qualquer um com acesso a traces pode lê-lo.
|
||||
2. **Isso muda a descrição da tarefa a cada kickoff.** A CrewAI Platform identifica tarefas por um hash MD5 da descrição; um valor rotativo significa que o hash muda por kickoff, o que quebra o mapeamento deploy-time → runtime das tarefas. Sintoma: os registros de tarefa aparecem como `pending_run` indefinidamente, ou apenas algumas das tarefas de um crew multi-task se registram.
|
||||
|
||||
O padrão baseado em ferramenta neste guia contorna ambas as questões: o prompt é estático, a ferramenta lê a env var em runtime e apenas um fingerprint do valor chega ao LLM.
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
- [Voltar à visão geral do Secrets Manager](/pt-BR/enterprise/features/secrets-manager/overview)
|
||||
- Uma vez verificado, descarte o crew de verificação. Crews reais devem seguir o mesmo padrão: segredos acessados via `os.environ` dentro de uma ferramenta, nunca substituídos em prompts.
|
||||
257
docs/edge/pt-BR/enterprise/features/tools-and-integrations.mdx
Normal file
257
docs/edge/pt-BR/enterprise/features/tools-and-integrations.mdx
Normal file
@@ -0,0 +1,257 @@
|
||||
---
|
||||
title: "Ferramentas & Integrações"
|
||||
description: "Conecte apps externos e gerencie ferramentas internas que seus agentes podem usar."
|
||||
icon: "wrench"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão geral
|
||||
|
||||
Ferramentas & Integrações é o hub central para conectar aplicações de terceiros e gerenciar ferramentas internas que seus agentes podem usar em tempo de execução.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Explorar
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Integrações" icon="plug">
|
||||
|
||||
## Aplicativos para Agentes (Integrações)
|
||||
|
||||
Conecte aplicações empresariais (por exemplo, Gmail, Google Drive, HubSpot, Slack) via OAuth para habilitar ações de agentes.
|
||||
|
||||
{" "}
|
||||
<Steps>
|
||||
<Step title="Conectar">
|
||||
Clique em <b>Conectar</b> no app desejado e conclua o OAuth.
|
||||
</Step>
|
||||
<Step title="Configurar">
|
||||
Ajuste escopos, gatilhos e ações disponíveis conforme necessário.
|
||||
</Step>
|
||||
<Step title="Usar em Agentes">
|
||||
Os serviços conectados ficam disponíveis como ferramentas para seus agentes.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
{" "}
|
||||
<Frame></Frame>
|
||||
|
||||
### Conectar sua conta
|
||||
|
||||
1. Acesse <Link href="https://app.crewai.com/crewai_plus/connectors">Integrações</Link>
|
||||
2. Clique em <b>Conectar</b> no serviço desejado
|
||||
3. Conclua o fluxo OAuth e conceda os escopos
|
||||
4. Copie seu Token Enterprise em <Link href="https://app.crewai.com/crewai_plus/settings/integrations">Configurações de Integração</Link>
|
||||
|
||||
{" "}
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
### Instalar ferramentas de integração
|
||||
|
||||
Para usar as integrações localmente, instale a versão mais recente do pacote `crewai-tools`.
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### Configuração de variável de ambiente
|
||||
|
||||
{" "}
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
### Exemplo de uso
|
||||
|
||||
{" "}
|
||||
<Tip>
|
||||
Use a nova abordagem simplificada para integrar aplicativos empresariais.
|
||||
Simplesmente especifique o aplicativo e suas ações diretamente na configuração
|
||||
do Agent.
|
||||
</Tip>
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente com capacidades do Gmail
|
||||
email_agent = Agent(
|
||||
role="Gerente de Email",
|
||||
goal="Gerenciar e organizar comunicações por email",
|
||||
backstory="Assistente de IA especializado em gestão de emails",
|
||||
apps=['gmail', 'gmail/send_email'] # Usando nome canônico 'gmail'
|
||||
)
|
||||
|
||||
email_task = Task(
|
||||
description="Criar e enviar follow-up para john@example.com sobre a atualização do projeto",
|
||||
agent=email_agent,
|
||||
expected_output="Confirmação de envio do email com sucesso"
|
||||
)
|
||||
|
||||
crew = Crew(agents=[email_agent], tasks=[email_task])
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### Filtrando ferramentas
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie agente com ações específicas do Gmail apenas
|
||||
gmail_agent = Agent(
|
||||
role="Gerente de Gmail",
|
||||
goal="Gerenciar comunicações e notificações no Gmail",
|
||||
backstory="Assistente de IA para coordenação de emails",
|
||||
apps=['gmail/fetch_emails'] # Usando nome canônico com ação específica
|
||||
)
|
||||
|
||||
notification_task = Task(
|
||||
description="Encontrar o email de john@example.com",
|
||||
agent=gmail_agent,
|
||||
expected_output="Email encontrado de john@example.com"
|
||||
)
|
||||
|
||||
crew = Crew(agents=[gmail_agent], tasks=[notification_task])
|
||||
```
|
||||
|
||||
Em um crew implantado, você pode especificar quais ações ficam disponíveis em cada integração na página de configurações do serviço.
|
||||
|
||||
{" "}
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
### Implantações com escopo (organizações multiusuário)
|
||||
|
||||
Você pode escopar cada integração para um usuário específico (por exemplo, usar a conta Gmail de um usuário).
|
||||
|
||||
{" "}
|
||||
<Tip>
|
||||
Útil quando diferentes equipes/usuários precisam manter o acesso a dados
|
||||
isolado.
|
||||
</Tip>
|
||||
|
||||
Use `user_bearer_token` para escopar a autenticação ao usuário solicitante. Se o usuário não estiver logado, o crew não usará integrações conectadas; caso contrário, usa o token padrão configurado na implantação.
|
||||
|
||||
{" "}
|
||||
<Frame></Frame>
|
||||
|
||||
{" "}
|
||||
<div id="catalog"></div>
|
||||
### Catálogo
|
||||
|
||||
#### Comunicação & Colaboração
|
||||
|
||||
- Gmail — Gerenciamento de emails e rascunhos
|
||||
- Slack — Notificações e alertas do workspace
|
||||
- Microsoft — Integração com Office 365 e Teams
|
||||
|
||||
#### Gestão de Projetos
|
||||
|
||||
- Jira — Rastreamento de issues e projetos
|
||||
- ClickUp — Gestão de tarefas e produtividade
|
||||
- Asana — Coordenação de tarefas de equipe
|
||||
- Notion — Páginas e bancos de dados
|
||||
- Linear — Gestão de bugs e projetos de software
|
||||
- GitHub — Repositórios e issues
|
||||
|
||||
#### CRM
|
||||
|
||||
- Salesforce — Contas e oportunidades
|
||||
- HubSpot — Pipeline de vendas e contatos
|
||||
- Zendesk — Tickets de suporte
|
||||
|
||||
#### Negócios & Finanças
|
||||
|
||||
- Stripe — Pagamentos e clientes
|
||||
- Shopify — E‑commerce e produtos
|
||||
|
||||
#### Produtividade & Armazenamento
|
||||
|
||||
- Google Sheets — Sincronização de planilhas
|
||||
- Google Calendar — Eventos e agenda
|
||||
- Box — Armazenamento de arquivos
|
||||
|
||||
…e mais por vir!
|
||||
|
||||
</Tab>
|
||||
<Tab title="Ferramentas Internas" icon="toolbox">
|
||||
|
||||
## Ferramentas Internas
|
||||
|
||||
Crie ferramentas localmente, publique no Repositório de Ferramentas da CrewAI AMP e use nos seus agentes.
|
||||
|
||||
{" "}
|
||||
<Tip>
|
||||
Antes de executar os comandos abaixo, faça login na sua conta CrewAI AMP:
|
||||
```bash crewai login ```
|
||||
</Tip>
|
||||
|
||||
{" "}
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
{" "}
|
||||
<Steps>
|
||||
<Step title="Criar">
|
||||
Criar uma nova ferramenta localmente. ```bash crewai tool create your-tool```
|
||||
</Step>
|
||||
<Step title="Publicar">
|
||||
Publicar a ferramenta no Repositório de Ferramentas. ```bash crewai tool
|
||||
publish ```
|
||||
</Step>
|
||||
<Step title="Instalar">
|
||||
Instalar a ferramenta do Repositório de Ferramentas. ```bash crewai tool
|
||||
install your-tool ```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Gerenciar:
|
||||
|
||||
- Nome e descrição
|
||||
- Visibilidade (Privado / Público)
|
||||
- Variáveis de ambiente necessárias
|
||||
- Histórico de versões e downloads
|
||||
- Acesso por equipe e função
|
||||
|
||||
{" "}
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Relacionados
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Repositório de Ferramentas"
|
||||
href="/pt-BR/enterprise/guides/tool-repository"
|
||||
icon="toolbox"
|
||||
>
|
||||
Publique e instale ferramentas para ampliar as capacidades dos seus crews.
|
||||
</Card>
|
||||
<Card
|
||||
title="Automação com Webhook"
|
||||
href="/pt-BR/enterprise/guides/webhook-automation"
|
||||
icon="bolt"
|
||||
>
|
||||
Automatize fluxos e integre com plataformas e serviços externos.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
138
docs/edge/pt-BR/enterprise/features/traces.mdx
Normal file
138
docs/edge/pt-BR/enterprise/features/traces.mdx
Normal file
@@ -0,0 +1,138 @@
|
||||
---
|
||||
title: Traces
|
||||
description: "Usando Traces para monitorar seus Crews"
|
||||
icon: "timeline"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP 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></Frame>
|
||||
|
||||
## Acessando os Traces
|
||||
|
||||
<Steps>
|
||||
<Step title="Navegue até a aba Traces">
|
||||
No seu painel do CrewAI AMP, 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></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></Frame>
|
||||
|
||||
### 3. Saída Final
|
||||
|
||||
Exibe o resultado final produzido pelo crew após a conclusão de todas as tarefas.
|
||||
|
||||
<Frame></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></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></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>
|
||||
|
||||
</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 AMP.
|
||||
</Card>
|
||||
87
docs/edge/pt-BR/enterprise/features/webhook-streaming.mdx
Normal file
87
docs/edge/pt-BR/enterprise/features/webhook-streaming.mdx
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: Webhook Streaming
|
||||
description: "Usando Webhook Streaming para transmitir eventos para o seu webhook"
|
||||
icon: "webhook"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP, 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:
|
||||
|
||||
# Exemplo de uso da API Kickoff com webhooks
|
||||
|
||||
```json
|
||||
{
|
||||
"inputs": { "foo": "bar" },
|
||||
"webhooks": {
|
||||
"events": ["crew_kickoff_started", "llm_call_started"],
|
||||
"url": "https://seu.endpoint/webhook",
|
||||
"realtime": false,
|
||||
"authentication": {
|
||||
"strategy": "bearer",
|
||||
"token": "meu-token-secreto"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
# Exemplo de evento enviado pelo webhook
|
||||
|
||||
```json
|
||||
{
|
||||
"events": [
|
||||
{
|
||||
"id": "id-do-evento",
|
||||
"execution_id": "id-da-execucao-do-crew",
|
||||
"timestamp": "2025-02-16T10:58:44.965Z",
|
||||
"type": "llm_call_started",
|
||||
"data": {
|
||||
"model": "gpt-4",
|
||||
"messages": [
|
||||
{ "role": "system", "content": "Você é um assistente." },
|
||||
{ "role": "user", "content": "Resuma este artigo." }
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
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>
|
||||
291
docs/edge/pt-BR/enterprise/guides/automation-triggers.mdx
Normal file
291
docs/edge/pt-BR/enterprise/guides/automation-triggers.mdx
Normal file
@@ -0,0 +1,291 @@
|
||||
---
|
||||
title: "Visão Geral de Triggers"
|
||||
description: "Entenda como os triggers da CrewAI AMP funcionam, como gerenciá-los e onde encontrar playbooks específicos de integração"
|
||||
icon: "bolt"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
Os triggers da CrewAI AMP conectam suas automações a eventos em tempo real nas ferramentas que sua equipe já usa. Em vez de fazer polling ou depender de execuções manuais, os triggers escutam mudanças — novos e‑mails, atualizações de calendário, alterações no CRM — e iniciam imediatamente a crew ou flow que você definiu.
|
||||
|
||||
<iframe
|
||||
className="w-full aspect-video rounded-xl"
|
||||
src="https://www.youtube.com/embed/TpQ45lAZh48"
|
||||
title="Visão geral dos triggers da CrewAI"
|
||||
frameBorder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowFullScreen
|
||||
></iframe>
|
||||
|
||||
### Playbooks de Integração
|
||||
|
||||
Os guias abaixo explicam, em detalhe, como habilitar e testar cada integração:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Trigger do Gmail" icon="envelope">
|
||||
<a href="/pt-BR/enterprise/guides/gmail-trigger">Dispare crews quando novos e‑mails chegarem ou threads forem atualizadas.</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Trigger do Google Calendar" icon="calendar-days">
|
||||
<a href="/pt-BR/enterprise/guides/google-calendar-trigger">
|
||||
Reaja a eventos de calendário criados, atualizados ou cancelados.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Trigger do Google Drive" icon="folder-open">
|
||||
<a href="/pt-BR/enterprise/guides/google-drive-trigger">
|
||||
Monitore uploads, edições e exclusões de arquivos no Drive.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Trigger do Outlook" icon="envelope-open">
|
||||
<a href="/pt-BR/enterprise/guides/outlook-trigger">
|
||||
Automatize respostas a novos e‑mails ou eventos removidos no Outlook.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Trigger do OneDrive" icon="cloud">
|
||||
<a href="/pt-BR/enterprise/guides/onedrive-trigger">
|
||||
Audite atividade e compartilhamentos de arquivos no OneDrive.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Trigger do Microsoft Teams" icon="comments">
|
||||
<a href="/pt-BR/enterprise/guides/microsoft-teams-trigger">
|
||||
Inicie workflows quando novos chats forem criados no Teams.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Trigger do HubSpot" icon="hubspot">
|
||||
<a href="/pt-BR/enterprise/guides/hubspot-trigger">
|
||||
Execute automações a partir de workflows e eventos de ciclo de vida no
|
||||
HubSpot.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Trigger do Salesforce" icon="salesforce">
|
||||
<a href="/pt-BR/enterprise/guides/salesforce-trigger">
|
||||
Conecte processos do Salesforce às suas crews para automação de CRM.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Trigger do Slack" icon="slack">
|
||||
<a href="/pt-BR/enterprise/guides/slack-trigger">
|
||||
Dispare crews diretamente de comandos slash no Slack.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
<Card title="Trigger do Zapier" icon="bolt">
|
||||
<a href="/pt-BR/enterprise/guides/zapier-trigger">Integre a CrewAI com milhares de apps suportados pelo Zapier.</a>
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Capacidades dos Triggers
|
||||
|
||||
Com triggers você pode:
|
||||
|
||||
- **Responder em tempo real** – Executar workflows automaticamente quando condições forem atendidas
|
||||
- **Integrar com sistemas externos** – Conectar Gmail, Outlook, OneDrive, JIRA, Slack, Stripe e muito mais
|
||||
- **Escalar automações** – Lidar com alto volume de eventos sem intervenção manual
|
||||
- **Manter contexto** – Acessar dados do trigger dentro das suas crews e flows
|
||||
|
||||
## Gerenciando Triggers
|
||||
|
||||
### Visualizando Triggers Disponíveis
|
||||
|
||||
1. Abra sua automação no painel da CrewAI
|
||||
2. Clique na aba **Triggers** para listar todas as integrações disponíveis
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/list-available-triggers.png"
|
||||
alt="Lista de triggers disponíveis"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
### Habilitando e Desabilitando
|
||||
|
||||
Cada trigger possui uma chave de ativação:
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/trigger-selected.png"
|
||||
alt="Alternância de trigger habilitado"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
- **Habilitado (azul)** – Executa a automação quando o evento ocorrer
|
||||
- **Desabilitado (cinza)** – Ignora eventos
|
||||
|
||||
As alterações são aplicadas imediatamente.
|
||||
|
||||
### Monitorando Execuções
|
||||
|
||||
Use a lista de execuções para acompanhar histórico, status e payloads:
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/list-executions.png"
|
||||
alt="Lista de execuções acionadas por triggers"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Construindo Automações Orientadas por Trigger
|
||||
|
||||
### Checklist de Configuração
|
||||
|
||||
Antes de ativar em produção, confirme que você:
|
||||
|
||||
- Conectou a integração em **Tools & Integrations** e concluiu OAuth ou configuração de API
|
||||
- Habilitou o trigger na automação correta
|
||||
- Definiu variáveis de ambiente necessárias (tokens, IDs de tenant, segredos)
|
||||
- Criou tarefas que analisam o payload no primeiro passo da crew/flow
|
||||
- Decidiu se usará `allow_crewai_trigger_context` para injetar contexto automaticamente
|
||||
- Configurou monitoramento (webhooks, históricos da CrewAI, alertas externos)
|
||||
|
||||
### Testando Triggers Localmente com CLI
|
||||
|
||||
A CLI da CrewAI fornece comandos poderosos para ajudá-lo a desenvolver e testar automações orientadas por triggers sem fazer deploy para produção.
|
||||
|
||||
#### Listar Triggers Disponíveis
|
||||
|
||||
Visualize todos os triggers disponíveis para suas integrações conectadas:
|
||||
|
||||
```bash
|
||||
crewai triggers list
|
||||
```
|
||||
|
||||
Este comando exibe todos os triggers disponíveis baseados nas suas integrações conectadas, mostrando:
|
||||
|
||||
- Nome da integração e status de conexão
|
||||
- Tipos de triggers disponíveis
|
||||
- Nomes e descrições dos triggers
|
||||
|
||||
#### Simular Execução de Trigger
|
||||
|
||||
Teste sua crew com payloads realistas de triggers antes do deployment:
|
||||
|
||||
```bash
|
||||
crewai triggers run <nome_do_trigger>
|
||||
```
|
||||
|
||||
Por exemplo:
|
||||
|
||||
```bash
|
||||
crewai triggers run microsoft_onedrive/file_changed
|
||||
```
|
||||
|
||||
Este comando:
|
||||
|
||||
- Executa sua crew localmente
|
||||
- Passa um payload de trigger completo e realista
|
||||
- Simula exatamente como sua crew será chamada em produção
|
||||
|
||||
<Warning>
|
||||
**Notas Importantes de Desenvolvimento:**
|
||||
- Use `crewai triggers run <trigger>` para simular execução de trigger durante o desenvolvimento
|
||||
- Usar `crewai run` NÃO simulará chamadas de trigger e não passará o payload do trigger
|
||||
- Após o deployment, sua crew será executada com o payload real do trigger
|
||||
- Se sua crew espera parâmetros que não estão no payload do trigger, a execução pode falhar
|
||||
</Warning>
|
||||
|
||||
### Triggers com Crews
|
||||
|
||||
Suas definições de crew funcionam naturalmente com triggers; basta ter uma tarefa que processe o payload recebido:
|
||||
|
||||
```python
|
||||
@CrewBase
|
||||
class MinhaCrewAutomatizada:
|
||||
@agent
|
||||
def pesquisador(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['pesquisador'],
|
||||
)
|
||||
|
||||
@task
|
||||
def analisar_payload_trigger(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['analisar_payload_trigger'],
|
||||
agent=self.pesquisador(),
|
||||
)
|
||||
|
||||
@task
|
||||
def analisar_conteudo_trigger(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['analisar_dados_trigger'],
|
||||
agent=self.pesquisador(),
|
||||
)
|
||||
```
|
||||
|
||||
### Integração com Flows
|
||||
|
||||
Flows oferecem controle adicional sobre o uso do payload:
|
||||
|
||||
#### Acessando o Payload
|
||||
|
||||
Todos os métodos `@start()` podem receber `crewai_trigger_payload`:
|
||||
|
||||
```python
|
||||
from crewai.flow import Flow, start, listen
|
||||
|
||||
class MeuFlowAutomatizado(Flow):
|
||||
@start()
|
||||
def lidar_com_trigger(self, crewai_trigger_payload: dict = None):
|
||||
if crewai_trigger_payload:
|
||||
trigger_id = crewai_trigger_payload.get('id')
|
||||
dados_evento = crewai_trigger_payload.get('payload', {})
|
||||
self.state.trigger_id = trigger_id
|
||||
self.state.trigger_type = dados_evento
|
||||
return dados_evento
|
||||
return None
|
||||
|
||||
@listen(lidar_com_trigger)
|
||||
def processar_dados(self, dados_trigger):
|
||||
# ... processa o trigger
|
||||
```
|
||||
|
||||
#### Acionando Crews a partir de Flows
|
||||
|
||||
```python
|
||||
@start()
|
||||
def delegar_para_crew(self, crewai_trigger_payload: dict = None):
|
||||
crew = MinhaCrewEspecializada()
|
||||
resultado = crew.crew().kickoff(
|
||||
inputs={
|
||||
'parametro_personalizado': "valor_personalizado",
|
||||
'crewai_trigger_payload': crewai_trigger_payload
|
||||
},
|
||||
)
|
||||
return resultado
|
||||
```
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
**Trigger não dispara:**
|
||||
|
||||
- Verifique se o trigger está habilitado na aba Triggers do seu deployment
|
||||
- Confira o status da conexão em Tools & Integrations
|
||||
- Garanta que todas as variáveis de ambiente necessárias estão configuradas
|
||||
|
||||
**Falhas de execução:**
|
||||
|
||||
- Consulte os logs de execução para detalhes do erro
|
||||
- Use `crewai triggers run <nome_do_trigger>` para testar localmente e ver a estrutura exata do payload
|
||||
- Verifique se sua crew pode processar o parâmetro `crewai_trigger_payload`
|
||||
- Garanta que sua crew não espera parâmetros que não estão incluídos no payload do trigger
|
||||
|
||||
**Problemas de desenvolvimento:**
|
||||
|
||||
- Sempre teste com `crewai triggers run <trigger>` antes de fazer deploy para ver o payload completo
|
||||
- Lembre-se que `crewai run` NÃO simula chamadas de trigger—use `crewai triggers run` em vez disso
|
||||
- Use `crewai triggers list` para verificar quais triggers estão disponíveis para suas integrações conectadas
|
||||
- Após o deployment, sua crew receberá o payload real do trigger, então teste minuciosamente localmente primeiro
|
||||
|
||||
Os triggers transformam suas implantações CrewAI em sistemas orientados por eventos, integrando-se perfeitamente aos processos e ferramentas já usados pelo seu time.
|
||||
54
docs/edge/pt-BR/enterprise/guides/azure-openai-setup.mdx
Normal file
54
docs/edge/pt-BR/enterprise/guides/azure-openai-setup.mdx
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: "Configuração do Azure OpenAI"
|
||||
description: "Configure o Azure OpenAI com o Crew Studio para conexões empresariais de LLM"
|
||||
icon: "microsoft"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
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 AMP > 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 AMP > 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
|
||||
48
docs/edge/pt-BR/enterprise/guides/build-crew.mdx
Normal file
48
docs/edge/pt-BR/enterprise/guides/build-crew.mdx
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: "Build Crew"
|
||||
description: "Uma Crew é um grupo de agentes que trabalham juntos para completar uma tarefa."
|
||||
icon: "people-arrows"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
[CrewAI AMP](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
|
||||
className="w-full aspect-video rounded-xl"
|
||||
src="https://www.youtube.com/embed/-kSOTtYzgEw"
|
||||
title="Building crews with the CrewAI CLI"
|
||||
frameBorder="0"
|
||||
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>
|
||||
63
docs/edge/pt-BR/enterprise/guides/capture_telemetry_logs.mdx
Normal file
63
docs/edge/pt-BR/enterprise/guides/capture_telemetry_logs.mdx
Normal file
@@ -0,0 +1,63 @@
|
||||
---
|
||||
title: "Exportação OpenTelemetry"
|
||||
description: "Exporte traces e logs das suas implantações CrewAI AMP para seu próprio coletor OpenTelemetry"
|
||||
icon: "magnifying-glass-chart"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
O CrewAI AMP pode exportar **traces** e **logs** do OpenTelemetry das suas implantações diretamente para seu próprio coletor. Isso permite que você monitore o desempenho dos agentes, rastreie chamadas de LLM e depure problemas usando sua stack de observabilidade existente.
|
||||
|
||||
Os dados de telemetria seguem as [convenções semânticas GenAI do OpenTelemetry](https://opentelemetry.io/docs/specs/semconv/gen-ai/) além de atributos adicionais específicos do CrewAI.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Conta CrewAI AMP" icon="users">
|
||||
Sua organização deve ter uma conta CrewAI AMP ativa.
|
||||
</Card>
|
||||
<Card title="Coletor OpenTelemetry" icon="server">
|
||||
Você precisa de um endpoint de coletor compatível com OpenTelemetry (por exemplo, seu próprio OTel Collector, Datadog, Grafana ou qualquer backend compatível com OTLP).
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Configurando um coletor
|
||||
|
||||
1. No CrewAI AMP, vá para **Settings** > **OpenTelemetry Collectors**.
|
||||
2. Clique em **Add Collector**.
|
||||
3. Selecione uma integração:
|
||||
- **OpenTelemetry Traces** e **OpenTelemetry Logs** — exporte para qualquer coletor ou backend compatível com OTLP.
|
||||
- **Datadog** — envie traces diretamente para a ingestão OTLP do Datadog, sem precisar de um coletor separado ou do Datadog Agent.
|
||||
4. Configure a conexão. Os campos dependem da integração selecionada:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="OpenTelemetry Traces / Logs">
|
||||
**OpenTelemetry Traces** e **OpenTelemetry Logs** são integrações separadas que compartilham os mesmos campos — escolha a que corresponde ao sinal que você quer exportar.
|
||||
|
||||
- **Endpoint** — O endpoint OTLP do seu coletor (por exemplo, `https://otel-collector.example.com:4317`).
|
||||
- **Service Name** — Um nome para identificar este serviço na sua plataforma de observabilidade.
|
||||
- **Custom Headers** *(opcional)* — Adicione headers de autenticação ou roteamento como pares chave-valor.
|
||||
- **Certificate** *(opcional)* — Forneça um certificado TLS se o seu coletor exigir um.
|
||||
|
||||
<Frame></Frame>
|
||||
</Tab>
|
||||
<Tab title="Datadog">
|
||||
- **Datadog Site Domain** — Apenas o host OTLP do seu site Datadog, sem protocolo ou caminho. O CrewAI monta o endpoint HTTPS OTLP completo para você. Use o host correspondente ao seu [site Datadog](https://docs.datadoghq.com/getting_started/site/):
|
||||
- `otlp.datadoghq.com` (US1)
|
||||
- `otlp.us3.datadoghq.com` (US3)
|
||||
- `otlp.us5.datadoghq.com` (US5)
|
||||
- `otlp.datadoghq.eu` (EU1)
|
||||
- `otlp.ap1.datadoghq.com` (AP1)
|
||||
- **API Key** — Sua chave de API do Datadog. Veja [como criar uma](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
|
||||
|
||||
A integração com o Datadog exporta **traces**.
|
||||
|
||||
<Frame></Frame>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
5. *(opcional)* Clique em **Test Connection** para verificar se o CrewAI consegue acessar o endpoint com as credenciais fornecidas.
|
||||
6. Clique em **Save**.
|
||||
|
||||
<Tip>
|
||||
Você pode adicionar múltiplos coletores — por exemplo, um para traces e outro para logs, ou enviar para diferentes backends para diferentes propósitos.
|
||||
</Tip>
|
||||
136
docs/edge/pt-BR/enterprise/guides/custom-mcp-server.mdx
Normal file
136
docs/edge/pt-BR/enterprise/guides/custom-mcp-server.mdx
Normal file
@@ -0,0 +1,136 @@
|
||||
---
|
||||
title: "Servidores MCP Personalizados"
|
||||
description: "Conecte seus próprios servidores MCP ao CrewAI AMP com acesso público, autenticação por token ou OAuth 2.0"
|
||||
icon: "plug"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
O CrewAI AMP suporta a conexão com qualquer servidor MCP que implemente o [Model Context Protocol](https://modelcontextprotocol.io/). Você pode conectar servidores públicos que não exigem autenticação, servidores protegidos por chave de API ou token bearer, e servidores que utilizam OAuth 2.0 para acesso delegado seguro.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Conta CrewAI AMP" icon="user">
|
||||
Você precisa de uma conta ativa no [CrewAI AMP](https://app.crewai.com).
|
||||
</Card>
|
||||
<Card title="URL do Servidor MCP" icon="link">
|
||||
A URL do servidor MCP que você deseja conectar. O servidor deve ser acessível pela internet e suportar transporte Streamable HTTP.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Adicionando um Servidor MCP Personalizado
|
||||
|
||||
<Steps>
|
||||
<Step title="Acesse Tools & Integrations">
|
||||
Navegue até **Tools & Integrations** no menu lateral esquerdo do CrewAI AMP e selecione a aba **Connections**.
|
||||
</Step>
|
||||
|
||||
<Step title="Inicie a adição de um Servidor MCP Personalizado">
|
||||
Clique no botão **Add Custom MCP Server**. Um diálogo aparecerá com o formulário de configuração.
|
||||
</Step>
|
||||
|
||||
<Step title="Preencha as informações básicas">
|
||||
- **Name** (obrigatório): Um nome descritivo para seu servidor MCP (ex.: "Meu Servidor de Ferramentas Internas").
|
||||
- **Description**: Um resumo opcional do que este servidor MCP fornece.
|
||||
- **Server URL** (obrigatório): A URL completa do endpoint do seu servidor MCP (ex.: `https://my-server.example.com/mcp`).
|
||||
</Step>
|
||||
|
||||
<Step title="Escolha um método de autenticação">
|
||||
Selecione um dos três métodos de autenticação disponíveis com base em como seu servidor MCP está protegido. Veja as seções abaixo para detalhes sobre cada método.
|
||||
</Step>
|
||||
|
||||
<Step title="Adicione headers personalizados (opcional)">
|
||||
Se seu servidor MCP requer headers adicionais em cada requisição (ex.: identificadores de tenant ou headers de roteamento), clique em **+ Add Header** e forneça o nome e valor do header. Você pode adicionar múltiplos headers personalizados.
|
||||
</Step>
|
||||
|
||||
<Step title="Crie a conexão">
|
||||
Clique em **Create MCP Server** para salvar a conexão. Seu servidor MCP personalizado aparecerá na lista de Connections e suas ferramentas estarão disponíveis para uso nas suas crews.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Métodos de Autenticação
|
||||
|
||||
### Sem Autenticação
|
||||
|
||||
Escolha esta opção quando seu servidor MCP é publicamente acessível e não requer nenhuma credencial. Isso é comum para servidores open-source ou servidores internos rodando atrás de uma VPN.
|
||||
|
||||
### Token de Autenticação
|
||||
|
||||
Use este método quando seu servidor MCP é protegido por uma chave de API ou token bearer.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/custom-mcp-auth-token.png" alt="Servidor MCP Personalizado com Token de Autenticação" />
|
||||
</Frame>
|
||||
|
||||
| Campo | Obrigatório | Descrição |
|
||||
|-------|-------------|-----------|
|
||||
| **Header Name** | Sim | O nome do header HTTP que carrega o token (ex.: `X-API-Key`, `Authorization`). |
|
||||
| **Value** | Sim | Sua chave de API ou token bearer. |
|
||||
| **Add to** | Não | Onde anexar a credencial — **Header** (padrão) ou **Query parameter**. |
|
||||
|
||||
<Tip>
|
||||
Se seu servidor espera um token `Bearer` no header `Authorization`, defina o Header Name como `Authorization` e o Value como `Bearer <seu-token>`.
|
||||
</Tip>
|
||||
|
||||
### OAuth 2.0
|
||||
|
||||
Use este método para servidores MCP que requerem autorização OAuth 2.0. O CrewAI gerenciará todo o fluxo OAuth, incluindo a renovação de tokens.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/custom-mcp-oauth.png" alt="Servidor MCP Personalizado com OAuth 2.0" />
|
||||
</Frame>
|
||||
|
||||
| Campo | Obrigatório | Descrição |
|
||||
|-------|-------------|-----------|
|
||||
| **Redirect URI** | — | Preenchido automaticamente e somente leitura. Copie esta URI e registre-a como URI de redirecionamento autorizada no seu provedor OAuth. |
|
||||
| **Authorization Endpoint** | Sim | A URL para onde os usuários são enviados para autorizar o acesso (ex.: `https://auth.example.com/oauth/authorize`). |
|
||||
| **Token Endpoint** | Sim | A URL usada para trocar o código de autorização por um token de acesso (ex.: `https://auth.example.com/oauth/token`). |
|
||||
| **Client ID** | Sim | O Client ID OAuth emitido pelo seu provedor. |
|
||||
| **Client Secret** | Não | O Client Secret OAuth. Não é necessário para clientes públicos usando PKCE. |
|
||||
| **Scopes** | Não | Lista de escopos separados por espaço a solicitar (ex.: `read write`). |
|
||||
| **Token Auth Method** | Não | Como as credenciais do cliente são enviadas ao trocar tokens — **Standard (POST body)** ou **Basic Auth (header)**. Padrão é Standard. |
|
||||
| **PKCE Supported** | Não | Ative se seu provedor OAuth suporta Proof Key for Code Exchange. Recomendado para maior segurança. |
|
||||
|
||||
<Info>
|
||||
**Discover OAuth Config**: Se seu provedor OAuth suporta OpenID Connect Discovery, clique no link **Discover OAuth Config** para preencher automaticamente os endpoints de autorização e token a partir da URL `/.well-known/openid-configuration` do provedor.
|
||||
</Info>
|
||||
|
||||
#### Configurando OAuth 2.0 Passo a Passo
|
||||
|
||||
<Steps>
|
||||
<Step title="Registre a URI de redirecionamento">
|
||||
Copie a **Redirect URI** exibida no formulário e adicione-a como URI de redirecionamento autorizada nas configurações do seu provedor OAuth.
|
||||
</Step>
|
||||
|
||||
<Step title="Insira os endpoints e credenciais">
|
||||
Preencha o **Authorization Endpoint**, **Token Endpoint**, **Client ID** e, opcionalmente, o **Client Secret** e **Scopes**.
|
||||
</Step>
|
||||
|
||||
<Step title="Configure o método de troca de tokens">
|
||||
Selecione o **Token Auth Method** apropriado. A maioria dos provedores usa o padrão **Standard (POST body)**. Alguns provedores mais antigos requerem **Basic Auth (header)**.
|
||||
</Step>
|
||||
|
||||
<Step title="Ative o PKCE (recomendado)">
|
||||
Marque **PKCE Supported** se seu provedor suporta. O PKCE adiciona uma camada extra de segurança ao fluxo de código de autorização e é recomendado para todas as novas integrações.
|
||||
</Step>
|
||||
|
||||
<Step title="Crie e autorize">
|
||||
Clique em **Create MCP Server**. Você será redirecionado ao seu provedor OAuth para autorizar o acesso. Uma vez autorizado, o CrewAI armazenará os tokens e os renovará automaticamente conforme necessário.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Usando Seu Servidor MCP Personalizado
|
||||
|
||||
Uma vez conectado, as ferramentas do seu servidor MCP personalizado aparecem junto com as conexões integradas na página **Tools & Integrations**. Você pode:
|
||||
|
||||
- **Atribuir ferramentas a agentes** nas suas crews, assim como qualquer outra ferramenta CrewAI.
|
||||
- **Gerenciar visibilidade** para controlar quais membros da equipe podem usar o servidor.
|
||||
- **Editar ou remover** a conexão a qualquer momento na lista de Connections.
|
||||
|
||||
<Warning>
|
||||
Se seu servidor MCP ficar inacessível ou as credenciais expirarem, as chamadas de ferramentas usando esse servidor falharão. Certifique-se de que a URL do servidor seja estável e as credenciais estejam atualizadas.
|
||||
</Warning>
|
||||
|
||||
<Card title="Precisa de Ajuda?" icon="headset" href="mailto:support@crewai.com">
|
||||
Entre em contato com nossa equipe de suporte para assistência com configuração ou resolução de problemas de servidores MCP personalizados.
|
||||
</Card>
|
||||
450
docs/edge/pt-BR/enterprise/guides/deploy-to-amp.mdx
Normal file
450
docs/edge/pt-BR/enterprise/guides/deploy-to-amp.mdx
Normal file
@@ -0,0 +1,450 @@
|
||||
---
|
||||
title: "Deploy para AMP"
|
||||
description: "Implante seu Crew ou Flow no CrewAI AMP"
|
||||
icon: "rocket"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Depois de criar um Crew ou Flow localmente (ou pelo Crew Studio), o próximo passo é
|
||||
implantá-lo na plataforma CrewAI AMP. 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="Projeto Pronto para Implantação" icon="check-circle">
|
||||
Você deve ter um Crew ou Flow funcionando localmente com sucesso.
|
||||
Siga nosso [guia de preparação](/pt-BR/enterprise/guides/prepare-for-deployment) para verificar a estrutura do seu projeto.
|
||||
</Card>
|
||||
<Card title="Repositório GitHub" icon="github">
|
||||
Seu código deve estar em um repositório do GitHub (para o método de integração com GitHub).
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Info>
|
||||
**Crews vs Flows**: Ambos os tipos de projeto podem ser implantados como "automações" no CrewAI AMP.
|
||||
O processo de implantação é o mesmo, mas eles têm estruturas de projeto diferentes.
|
||||
Veja [Preparar para Implantação](/pt-BR/enterprise/guides/prepare-for-deployment) para detalhes.
|
||||
</Info>
|
||||
|
||||
## Opção 1: Implantar Usando o CrewAI CLI
|
||||
|
||||
A CLI fornece a maneira mais rápida de implantar Crews ou Flows desenvolvidos localmente na plataforma AMP.
|
||||
A CLI detecta automaticamente o tipo do seu projeto a partir do `pyproject.toml` e faz o build adequadamente.
|
||||
|
||||
<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 AMP:
|
||||
|
||||
```bash
|
||||
# Se já possui uma conta CrewAI AMP, ou deseja criar uma:
|
||||
crewai login
|
||||
```
|
||||
|
||||
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 cerca de 1 minuto.
|
||||
</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 ou Flows diretamente pela interface web do CrewAI AMP conectando sua conta do GitHub. Esta abordagem não requer utilizar a CLI na sua máquina local. A plataforma detecta automaticamente o tipo do seu projeto e trata o build adequadamente.
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step title="Enviar para o GitHub">
|
||||
|
||||
Você precisa enviar 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 AMP">
|
||||
|
||||
1. Faça login em [CrewAI AMP](https://app.crewai.com)
|
||||
2. Clique no botão "Connect GitHub"
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Selecionar o Repositório">
|
||||
|
||||
Após conectar sua conta GitHub, você poderá selecionar qual repositório deseja implantar:
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
<Tip>
|
||||
Se seu Crew ou Flow estiver dentro de uma subpasta de monorepo, expanda
|
||||
**Advanced** e defina um diretório de trabalho antes de implantar. Consulte
|
||||
[Implantações em Monorepo](/pt-BR/enterprise/guides/monorepo-deployments).
|
||||
</Tip>
|
||||
|
||||
</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>
|
||||
|
||||
</Frame>
|
||||
|
||||
<Info>
|
||||
Usando pacotes Python privados? Você também precisará adicionar suas credenciais de registro aqui.
|
||||
Consulte [Registros de Pacotes Privados](/pt-BR/enterprise/guides/private-package-registry) para as variáveis necessárias.
|
||||
</Info>
|
||||
|
||||
</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 cerca de 1 minuto
|
||||
|
||||
<Frame>
|
||||
|
||||
</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>
|
||||
|
||||
## Opção 3: Reimplantar Usando API (Integração CI/CD)
|
||||
|
||||
Para implantações automatizadas em pipelines CI/CD, você pode usar a API do CrewAI para acionar reimplantações de crews existentes. Isso é particularmente útil para GitHub Actions, Jenkins ou outros workflows de automação.
|
||||
|
||||
<Steps>
|
||||
<Step title="Obtenha Seu Token de Acesso Pessoal">
|
||||
|
||||
Navegue até as configurações da sua conta CrewAI AMP para gerar um token de API:
|
||||
|
||||
1. Acesse [app.crewai.com](https://app.crewai.com)
|
||||
2. Clique em **Settings** → **Account** → **Personal Access Token**
|
||||
3. Gere um novo token e copie-o com segurança
|
||||
4. Armazene este token como um secret no seu sistema CI/CD
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Encontre o UUID da Sua Automação">
|
||||
|
||||
Localize o identificador único do seu crew implantado:
|
||||
|
||||
1. Acesse **Automations** no seu dashboard CrewAI AMP
|
||||
2. Selecione sua automação/crew existente
|
||||
3. Clique em **Additional Details**
|
||||
4. Copie o **UUID** - este identifica sua implantação específica do crew
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Acione a Reimplantação via API">
|
||||
|
||||
Use o endpoint da API de Deploy para acionar uma reimplantação:
|
||||
|
||||
```bash
|
||||
curl -i -X POST \
|
||||
-H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
|
||||
https://app.crewai.com/crewai_plus/api/v1/crews/YOUR-AUTOMATION-UUID/deploy
|
||||
|
||||
# HTTP/2 200
|
||||
# content-type: application/json
|
||||
#
|
||||
# {
|
||||
# "uuid": "your-automation-uuid",
|
||||
# "status": "Deploy Enqueued",
|
||||
# "public_url": "https://your-crew-deployment.crewai.com",
|
||||
# "token": "your-bearer-token"
|
||||
# }
|
||||
```
|
||||
|
||||
<Info>
|
||||
Se sua automação foi criada originalmente conectada ao Git, a API automaticamente puxará as últimas alterações do seu repositório antes de reimplantar.
|
||||
</Info>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Exemplo de Integração com GitHub Actions">
|
||||
|
||||
Aqui está um workflow do GitHub Actions com gatilhos de implantação mais complexos:
|
||||
|
||||
```yaml
|
||||
name: Deploy CrewAI Automation
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
pull_request:
|
||||
types: [ labeled ]
|
||||
release:
|
||||
types: [ published ]
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
if: |
|
||||
(github.event_name == 'push' && github.ref == 'refs/heads/main') ||
|
||||
(github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'deploy')) ||
|
||||
(github.event_name == 'release')
|
||||
steps:
|
||||
- name: Trigger CrewAI Redeployment
|
||||
run: |
|
||||
curl -X POST \
|
||||
-H "Authorization: Bearer ${{ secrets.CREWAI_PAT }}" \
|
||||
https://app.crewai.com/crewai_plus/api/v1/crews/${{ secrets.CREWAI_AUTOMATION_UUID }}/deploy
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Adicione `CREWAI_PAT` e `CREWAI_AUTOMATION_UUID` como secrets do repositório. Para implantações de PR, adicione um label "deploy" para acionar o workflow.
|
||||
</Tip>
|
||||
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## Interaja com Sua Automação Implantada
|
||||
|
||||
Após a implantação, você pode acessar seu crew através 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
|
||||
|
||||
## Solução de Problemas em Falhas de Implantação
|
||||
|
||||
Se sua implantação falhar, verifique estes problemas comuns:
|
||||
|
||||
### Falhas de Build
|
||||
|
||||
#### Arquivo uv.lock Ausente
|
||||
|
||||
**Sintoma**: Build falha no início com erros de resolução de dependências
|
||||
|
||||
**Solução**: Gere e faça commit do arquivo lock:
|
||||
|
||||
```bash
|
||||
uv lock
|
||||
git add uv.lock
|
||||
git commit -m "Add uv.lock for deployment"
|
||||
git push
|
||||
```
|
||||
|
||||
<Warning>
|
||||
O arquivo `uv.lock` é obrigatório para todas as implantações. Sem ele, a plataforma
|
||||
não consegue instalar suas dependências de forma confiável.
|
||||
</Warning>
|
||||
|
||||
#### Estrutura de Projeto Incorreta
|
||||
|
||||
**Sintoma**: Erros "Could not find entry point" ou "Module not found"
|
||||
|
||||
**Solução**: Verifique se seu projeto corresponde à estrutura esperada:
|
||||
|
||||
- **Crews JSON-first**: Mantenha `crew.jsonc` ou `crew.json` e `agents/` na raiz do projeto
|
||||
- **Crews clássicas**: Use `src/project_name/main.py` com uma função de entrada `run()`
|
||||
- **Flows**: Use `src/project_name/main.py` com uma função de entrada `kickoff()`
|
||||
|
||||
Veja [Preparar para Implantação](/pt-BR/enterprise/guides/prepare-for-deployment) para diagramas de estrutura detalhados.
|
||||
|
||||
#### Decorador CrewBase Ausente em uma Crew Clássica
|
||||
|
||||
**Sintoma**: Erros "Crew not found", "Config not found" ou erros de configuração de agent/task
|
||||
|
||||
**Solução**: Para crews clássicas Python/YAML, certifique-se de que todas as classes crew usam o decorador `@CrewBase`. Crews JSON-first não precisam desse decorador.
|
||||
|
||||
```python
|
||||
from crewai.project import CrewBase, agent, crew, task
|
||||
|
||||
@CrewBase # Este decorador é OBRIGATÓRIO
|
||||
class YourCrew():
|
||||
"""Descrição do seu crew"""
|
||||
|
||||
@agent
|
||||
def my_agent(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['my_agent'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# ... resto da definição do crew
|
||||
```
|
||||
|
||||
<Info>
|
||||
Isso se aplica a classes crew Python clássicas, incluindo crews clássicas embutidas em projetos Flow.
|
||||
Crews JSON-first são validadas a partir de `crew.jsonc` e `agents/`.
|
||||
</Info>
|
||||
|
||||
#### Tipo Incorreto no pyproject.toml
|
||||
|
||||
**Sintoma**: Build tem sucesso mas falha em runtime, ou comportamento inesperado
|
||||
|
||||
**Solução**: Verifique se a seção `[tool.crewai]` corresponde ao tipo do seu projeto:
|
||||
|
||||
```toml
|
||||
# Para projetos Crew:
|
||||
[tool.crewai]
|
||||
type = "crew"
|
||||
|
||||
# Para projetos Flow:
|
||||
[tool.crewai]
|
||||
type = "flow"
|
||||
```
|
||||
|
||||
### Falhas de Runtime
|
||||
|
||||
#### Falhas de Conexão com LLM
|
||||
|
||||
**Sintoma**: Erros de chave API, "model not found" ou falhas de autenticação
|
||||
|
||||
**Solução**:
|
||||
1. Verifique se a chave API do seu provedor LLM está corretamente definida nas variáveis de ambiente
|
||||
2. Certifique-se de que os nomes das variáveis de ambiente correspondem ao que seu código espera
|
||||
3. Teste localmente com exatamente as mesmas variáveis de ambiente antes de implantar
|
||||
|
||||
#### Erros de Execução do Crew
|
||||
|
||||
**Sintoma**: Crew inicia mas falha durante a execução
|
||||
|
||||
**Solução**:
|
||||
1. Verifique os logs de execução no dashboard AMP (aba Traces)
|
||||
2. Verifique se todas as ferramentas têm as chaves API necessárias configuradas
|
||||
3. Para crews JSON-first, valide `crew.jsonc` e os arquivos referenciados em `agents/`
|
||||
4. Para crews clássicas, verifique se `agents.yaml` e `tasks.yaml` são válidos
|
||||
|
||||
<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 AMP.
|
||||
</Card>
|
||||
179
docs/edge/pt-BR/enterprise/guides/enable-crew-studio.mdx
Normal file
179
docs/edge/pt-BR/enterprise/guides/enable-crew-studio.mdx
Normal file
@@ -0,0 +1,179 @@
|
||||
---
|
||||
title: "Ativar Crew Studio"
|
||||
description: "Ativando o Crew Studio no CrewAI AMP"
|
||||
icon: "comments"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<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>
|
||||
|
||||
</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 AMP
|
||||
|
||||
## 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 AMP 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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
|
||||
</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 AMP.
|
||||
</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 AMP
|
||||
- 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 AMP.
|
||||
</Card>
|
||||
97
docs/edge/pt-BR/enterprise/guides/gmail-trigger.mdx
Normal file
97
docs/edge/pt-BR/enterprise/guides/gmail-trigger.mdx
Normal file
@@ -0,0 +1,97 @@
|
||||
---
|
||||
title: "Gmail Trigger"
|
||||
description: "Trigger automations when Gmail events occur (e.g., new emails, labels)."
|
||||
icon: "envelope"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Use the Gmail Trigger to kick off your deployed crews when Gmail events happen in connected accounts, such as receiving a new email or messages matching a label/filter.
|
||||
|
||||
<Tip>
|
||||
Make sure Gmail is connected in Tools & Integrations and the trigger is
|
||||
enabled for your deployment.
|
||||
</Tip>
|
||||
|
||||
## Enabling the Gmail Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **Gmail** and switch the toggle to enable
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/trigger-selected.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Process new emails
|
||||
|
||||
When a new email arrives, the Gmail Trigger will send the payload to your Crew or Flow. Below is a Crew example that parses and processes the trigger payload.
|
||||
|
||||
```python
|
||||
@CrewBase
|
||||
class GmailProcessingCrew:
|
||||
@agent
|
||||
def parser(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['parser'],
|
||||
)
|
||||
|
||||
@task
|
||||
def parse_gmail_payload(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['parse_gmail_payload'],
|
||||
agent=self.parser(),
|
||||
)
|
||||
|
||||
@task
|
||||
def act_on_email(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['act_on_email'],
|
||||
agent=self.parser(),
|
||||
)
|
||||
```
|
||||
|
||||
The Gmail payload will be available via the standard context mechanisms.
|
||||
|
||||
### Testando Localmente
|
||||
|
||||
Teste sua integração de trigger do Gmail localmente usando a CLI da CrewAI:
|
||||
|
||||
```bash
|
||||
# Visualize todos os triggers disponíveis
|
||||
crewai triggers list
|
||||
|
||||
# Simule um trigger do Gmail com payload realista
|
||||
crewai triggers run gmail/new_email_received
|
||||
```
|
||||
|
||||
O comando `crewai triggers run` executará sua crew com um payload completo do Gmail, permitindo que você teste sua lógica de parsing antes do deployment.
|
||||
|
||||
<Warning>
|
||||
Use `crewai triggers run gmail/new_email_received` (não `crewai run`) para
|
||||
simular execução de trigger durante o desenvolvimento. Após o deployment, sua
|
||||
crew receberá automaticamente o payload do trigger.
|
||||
</Warning>
|
||||
|
||||
## Monitoring Executions
|
||||
|
||||
Track history and performance of triggered runs:
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/list-executions.png"
|
||||
alt="List of executions triggered by automation"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Ensure Gmail is connected in Tools & Integrations
|
||||
- Verify the Gmail Trigger is enabled on the Triggers tab
|
||||
- Teste localmente com `crewai triggers run gmail/new_email_received` para ver a estrutura exata do payload
|
||||
- Check the execution logs and confirm the payload is passed as `crewai_trigger_payload`
|
||||
- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: "Google Calendar Trigger"
|
||||
description: "Kick off crews when Google Calendar events are created, updated, or cancelled"
|
||||
icon: "calendar"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Use the Google Calendar trigger to launch automations whenever calendar events change. Common use cases include briefing a team before a meeting, notifying stakeholders when a critical event is cancelled, or summarizing daily schedules.
|
||||
|
||||
<Tip>
|
||||
Make sure Google Calendar is connected in **Tools & Integrations** and enabled
|
||||
for the deployment you want to automate.
|
||||
</Tip>
|
||||
|
||||
## Enabling the Google Calendar Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **Google Calendar** and switch the toggle to enable
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/calendar-trigger.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Summarize meeting details
|
||||
|
||||
The snippet below mirrors the `calendar-event-crew.py` example in the trigger repository. It parses the payload, analyses the attendees and timing, and produces a meeting brief for downstream tools.
|
||||
|
||||
```python
|
||||
from calendar_event_crew import GoogleCalendarEventTrigger
|
||||
|
||||
crew = GoogleCalendarEventTrigger().crew()
|
||||
result = crew.kickoff({
|
||||
"crewai_trigger_payload": calendar_payload,
|
||||
})
|
||||
print(result.raw)
|
||||
```
|
||||
|
||||
Use `crewai_trigger_payload` exactly as it is delivered by the trigger so the crew can extract the proper fields.
|
||||
|
||||
## Testando Localmente
|
||||
|
||||
Teste sua integração de trigger do Google Calendar localmente usando a CLI da CrewAI:
|
||||
|
||||
```bash
|
||||
# Visualize todos os triggers disponíveis
|
||||
crewai triggers list
|
||||
|
||||
# Simule um trigger do Google Calendar com payload realista
|
||||
crewai triggers run google_calendar/event_changed
|
||||
```
|
||||
|
||||
O comando `crewai triggers run` executará sua crew com um payload completo do Calendar, permitindo que você teste sua lógica de parsing antes do deployment.
|
||||
|
||||
<Warning>
|
||||
Use `crewai triggers run google_calendar/event_changed` (não `crewai run`)
|
||||
para simular execução de trigger durante o desenvolvimento. Após o deployment,
|
||||
sua crew receberá automaticamente o payload do trigger.
|
||||
</Warning>
|
||||
|
||||
## Monitoring Executions
|
||||
|
||||
The **Executions** list in the deployment dashboard tracks every triggered run and surfaces payload metadata, output summaries, and errors.
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/list-executions.png"
|
||||
alt="List of executions triggered by automation"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Ensure the correct Google account is connected and the trigger is enabled
|
||||
- Teste localmente com `crewai triggers run google_calendar/event_changed` para ver a estrutura exata do payload
|
||||
- Confirm your workflow handles all-day events (payloads use `start.date` and `end.date` instead of timestamps)
|
||||
- Check execution logs if reminders or attendee arrays are missing—calendar permissions can limit fields in the payload
|
||||
- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger
|
||||
80
docs/edge/pt-BR/enterprise/guides/google-drive-trigger.mdx
Normal file
80
docs/edge/pt-BR/enterprise/guides/google-drive-trigger.mdx
Normal file
@@ -0,0 +1,80 @@
|
||||
---
|
||||
title: "Google Drive Trigger"
|
||||
description: "Respond to Google Drive file events with automated crews"
|
||||
icon: "folder"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Trigger your automations when files are created, updated, or removed in Google Drive. Typical workflows include summarizing newly uploaded content, enforcing sharing policies, or notifying owners when critical files change.
|
||||
|
||||
<Tip>
|
||||
Connect Google Drive in **Tools & Integrations** and confirm the trigger is
|
||||
enabled for the automation you want to monitor.
|
||||
</Tip>
|
||||
|
||||
## Enabling the Google Drive Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **Google Drive** and switch the toggle to enable
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/gdrive-trigger.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Summarize file activity
|
||||
|
||||
The drive example crews parse the payload to extract file metadata, evaluate permissions, and publish a summary.
|
||||
|
||||
```python
|
||||
from drive_file_crew import GoogleDriveFileTrigger
|
||||
|
||||
crew = GoogleDriveFileTrigger().crew()
|
||||
crew.kickoff({
|
||||
"crewai_trigger_payload": drive_payload,
|
||||
})
|
||||
```
|
||||
|
||||
## Testando Localmente
|
||||
|
||||
Teste sua integração de trigger do Google Drive localmente usando a CLI da CrewAI:
|
||||
|
||||
```bash
|
||||
# Visualize todos os triggers disponíveis
|
||||
crewai triggers list
|
||||
|
||||
# Simule um trigger do Google Drive com payload realista
|
||||
crewai triggers run google_drive/file_changed
|
||||
```
|
||||
|
||||
O comando `crewai triggers run` executará sua crew com um payload completo do Drive, permitindo que você teste sua lógica de parsing antes do deployment.
|
||||
|
||||
<Warning>
|
||||
Use `crewai triggers run google_drive/file_changed` (não `crewai run`) para
|
||||
simular execução de trigger durante o desenvolvimento. Após o deployment, sua
|
||||
crew receberá automaticamente o payload do trigger.
|
||||
</Warning>
|
||||
|
||||
## Monitoring Executions
|
||||
|
||||
Track history and performance of triggered runs with the **Executions** list in the deployment dashboard.
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/list-executions.png"
|
||||
alt="List of executions triggered by automation"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Verify Google Drive is connected and the trigger toggle is enabled
|
||||
- Teste localmente com `crewai triggers run google_drive/file_changed` para ver a estrutura exata do payload
|
||||
- If a payload is missing permission data, ensure the connected account has access to the file or folder
|
||||
- The trigger sends file IDs only; use the Drive API if you need to fetch binary content during the crew run
|
||||
- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger
|
||||
65
docs/edge/pt-BR/enterprise/guides/hubspot-trigger.mdx
Normal file
65
docs/edge/pt-BR/enterprise/guides/hubspot-trigger.mdx
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: "Gatilho HubSpot"
|
||||
description: "Acione crews do CrewAI diretamente a partir de Workflows do HubSpot"
|
||||
icon: "hubspot"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
Este guia fornece um processo passo a passo para configurar gatilhos do HubSpot para o CrewAI AMP, permitindo iniciar crews diretamente a partir de Workflows do HubSpot.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
- Uma conta CrewAI AMP
|
||||
- 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 AMP">
|
||||
- Faça login na sua `Conta CrewAI AMP > Triggers` - Selecione `HubSpot` na
|
||||
lista de gatilhos disponíveis - Escolha a conta HubSpot que deseja conectar
|
||||
ao CrewAI AMP - Siga as instruções na tela para autorizar o acesso do CrewAI
|
||||
AMP à sua conta HubSpot - Uma mensagem de confirmação aparecerá assim que o
|
||||
HubSpot estiver conectado com sucesso ao CrewAI AMP
|
||||
</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).
|
||||
157
docs/edge/pt-BR/enterprise/guides/human-in-the-loop.mdx
Normal file
157
docs/edge/pt-BR/enterprise/guides/human-in-the-loop.mdx
Normal file
@@ -0,0 +1,157 @@
|
||||
---
|
||||
title: "Workflows HITL"
|
||||
description: "Aprenda como implementar workflows Human-In-The-Loop no CrewAI para decisões aprimoradas"
|
||||
icon: "user-check"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
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 Enterprise.
|
||||
|
||||
## Abordagens HITL no CrewAI
|
||||
|
||||
CrewAI oferece duas abordagens para implementar workflows human-in-the-loop:
|
||||
|
||||
| Abordagem | Melhor Para | Versão |
|
||||
|----------|----------|---------|
|
||||
| **Baseada em Flow** (decorador `@human_feedback`) | Produção com UI Enterprise, workflows email-first, recursos completos da plataforma | **1.8.0+** |
|
||||
| **Baseada em Webhook** | Integrações customizadas, sistemas externos (Slack, Teams, etc.), configurações legadas | Todas as versões |
|
||||
|
||||
## HITL Baseado em Flow com Plataforma Enterprise
|
||||
|
||||
<Note>
|
||||
O decorador `@human_feedback` requer **CrewAI versão 1.8.0 ou superior**.
|
||||
</Note>
|
||||
|
||||
Ao usar o decorador `@human_feedback` em seus Flows, o CrewAI Enterprise oferece um **sistema HITL email-first** que permite que qualquer pessoa com um endereço de email responda a solicitações de revisão:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Design Email-First" icon="envelope">
|
||||
Respondentes recebem notificações por email e podem responder diretamente—nenhum login necessário.
|
||||
</Card>
|
||||
<Card title="Revisão no Dashboard" icon="desktop">
|
||||
Revise e responda a solicitações HITL no dashboard Enterprise quando preferir.
|
||||
</Card>
|
||||
<Card title="Roteamento Flexível" icon="route">
|
||||
Direcione solicitações para emails específicos com base em padrões de método ou obtenha do estado do flow.
|
||||
</Card>
|
||||
<Card title="Resposta Automática" icon="clock">
|
||||
Configure respostas automáticas de fallback quando nenhum humano responder dentro do timeout.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Principais Benefícios
|
||||
|
||||
- **Respondentes externos**: Qualquer pessoa com email pode responder, mesmo não sendo usuário da plataforma
|
||||
- **Atribuição dinâmica**: Obtenha o email do responsável do estado do flow (ex: `account_owner_email`)
|
||||
- **Configuração simples**: Roteamento baseado em email é mais fácil de configurar do que gerenciamento de usuários/funções
|
||||
- **Fallback do criador do deployment**: Se nenhuma regra de roteamento corresponder, o criador do deployment é notificado
|
||||
|
||||
<Tip>
|
||||
Para detalhes de implementação do decorador `@human_feedback`, consulte o guia [Feedback Humano em Flows](/pt-BR/learn/human-feedback-in-flows).
|
||||
</Tip>
|
||||
|
||||
## Configurando Workflows HITL Baseados em Webhook
|
||||
|
||||
Para integrações customizadas com sistemas externos como Slack, Microsoft Teams ou suas próprias aplicações, você pode usar a abordagem baseada em webhook:
|
||||
|
||||
<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>
|
||||
**Crítico: URLs de Webhook Devem Ser Fornecidas Novamente**:
|
||||
Você **deve** fornecer as mesmas URLs de webhook (`taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`) na chamada de resume que você usou na chamada de kickoff. As configurações de webhook **NÃO** são automaticamente transferidas do kickoff - elas devem ser explicitamente incluídas na solicitação de resume para continuar recebendo notificações de conclusão de tarefa, etapas do agente e conclusão do crew.
|
||||
</Warning>
|
||||
|
||||
Exemplo de chamada resume com webhooks:
|
||||
```bash
|
||||
curl -X POST {BASE_URL}/resume \
|
||||
-H "Authorization: Bearer YOUR_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"execution_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
|
||||
"task_id": "research_task",
|
||||
"human_feedback": "Ótimo trabalho! Por favor, adicione mais detalhes.",
|
||||
"is_approve": true,
|
||||
"taskWebhookUrl": "https://your-server.com/webhooks/task",
|
||||
"stepWebhookUrl": "https://your-server.com/webhooks/step",
|
||||
"crewWebhookUrl": "https://your-server.com/webhooks/crew"
|
||||
}'
|
||||
```
|
||||
|
||||
<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
|
||||
|
||||
## Saiba Mais
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Gerenciamento HITL para Flows" icon="users-gear" href="/pt-BR/enterprise/features/flow-hitl-management">
|
||||
Explore os recursos completos da plataforma HITL para Flows, incluindo notificações por email, regras de roteamento, resposta automática e análises.
|
||||
</Card>
|
||||
<Card title="Feedback Humano em Flows" icon="code" href="/pt-BR/learn/human-feedback-in-flows">
|
||||
Guia de implementação para o decorador `@human_feedback` em seus Flows.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
178
docs/edge/pt-BR/enterprise/guides/kickoff-crew.mdx
Normal file
178
docs/edge/pt-BR/enterprise/guides/kickoff-crew.mdx
Normal file
@@ -0,0 +1,178 @@
|
||||
---
|
||||
title: "Kickoff Crew"
|
||||
description: "Inicie um Crew no CrewAI AMP"
|
||||
icon: "flag-checkered"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Uma vez que você tenha implantado seu crew na plataforma CrewAI AMP, é 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 AMP](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></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></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></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></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></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 AMP.
|
||||
|
||||
### 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>
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: "Microsoft Teams Trigger"
|
||||
description: "Kick off crews from Microsoft Teams chat activity"
|
||||
icon: "microsoft"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Use the Microsoft Teams trigger to start automations whenever a new chat is created. Common patterns include summarizing inbound requests, routing urgent messages to support teams, or creating follow-up tasks in other systems.
|
||||
|
||||
<Tip>
|
||||
Confirm Microsoft Teams is connected under **Tools & Integrations** and
|
||||
enabled in the **Triggers** tab for your deployment.
|
||||
</Tip>
|
||||
|
||||
## Enabling the Microsoft Teams Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **Microsoft Teams** and switch the toggle to enable
|
||||
|
||||
<Frame caption="Microsoft Teams trigger connection">
|
||||
<img
|
||||
src="/images/enterprise/msteams-trigger.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Summarize a new chat thread
|
||||
|
||||
```python
|
||||
from teams_chat_created_crew import MicrosoftTeamsChatTrigger
|
||||
|
||||
crew = MicrosoftTeamsChatTrigger().crew()
|
||||
result = crew.kickoff({
|
||||
"crewai_trigger_payload": teams_payload,
|
||||
})
|
||||
print(result.raw)
|
||||
```
|
||||
|
||||
The crew parses thread metadata (subject, created time, roster) and generates an action plan for the receiving team.
|
||||
|
||||
## Testando Localmente
|
||||
|
||||
Teste sua integração de trigger do Microsoft Teams localmente usando a CLI da CrewAI:
|
||||
|
||||
```bash
|
||||
# Visualize todos os triggers disponíveis
|
||||
crewai triggers list
|
||||
|
||||
# Simule um trigger do Microsoft Teams com payload realista
|
||||
crewai triggers run microsoft_teams/teams_message_created
|
||||
```
|
||||
|
||||
O comando `crewai triggers run` executará sua crew com um payload completo do Teams, permitindo que você teste sua lógica de parsing antes do deployment.
|
||||
|
||||
<Warning>
|
||||
Use `crewai triggers run microsoft_teams/teams_message_created` (não `crewai
|
||||
run`) para simular execução de trigger durante o desenvolvimento. Após o
|
||||
deployment, sua crew receberá automaticamente o payload do trigger.
|
||||
</Warning>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Ensure the Teams connection is active; it must be refreshed if the tenant revokes permissions
|
||||
- Teste localmente com `crewai triggers run microsoft_teams/teams_message_created` para ver a estrutura exata do payload
|
||||
- Confirm the webhook subscription in Microsoft 365 is still valid if payloads stop arriving
|
||||
- Review execution logs for payload shape mismatches—Graph notifications may omit fields when a chat is private or restricted
|
||||
- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger
|
||||
234
docs/edge/pt-BR/enterprise/guides/monorepo-deployments.mdx
Normal file
234
docs/edge/pt-BR/enterprise/guides/monorepo-deployments.mdx
Normal file
@@ -0,0 +1,234 @@
|
||||
---
|
||||
title: "Implantações em Monorepo"
|
||||
description: "Implante um Crew ou Flow a partir de uma subpasta em um repositório maior"
|
||||
icon: "folder-tree"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Use um diretório de trabalho quando seu Crew ou Flow estiver dentro de um
|
||||
repositório maior. O CrewAI AMP valida, faz o build e executa a automação a
|
||||
partir dessa subpasta em vez da raiz do repositório.
|
||||
</Note>
|
||||
|
||||
## Quando Usar
|
||||
|
||||
Implantações em monorepo são úteis quando um repositório contém múltiplas
|
||||
automações, pacotes compartilhados ou outro código de aplicação:
|
||||
|
||||
```text
|
||||
company-ai/
|
||||
|-- uv.lock
|
||||
|-- packages/
|
||||
| `-- shared_tools/
|
||||
`-- crews/
|
||||
|-- support_agent/
|
||||
| |-- pyproject.toml
|
||||
| |-- crew.jsonc
|
||||
| `-- agents/
|
||||
| `-- support_agent.jsonc
|
||||
`-- research_flow/
|
||||
|-- pyproject.toml
|
||||
`-- src/
|
||||
`-- research_flow/
|
||||
`-- main.py
|
||||
```
|
||||
|
||||
Para implantar `support_agent`, defina o diretório de trabalho como:
|
||||
|
||||
```text
|
||||
crews/support_agent
|
||||
```
|
||||
|
||||
O AMP ainda baixa ou recebe o repositório inteiro, mas trata a pasta
|
||||
selecionada como a raiz do projeto da automação.
|
||||
|
||||
## O Que o Diretório de Trabalho Controla
|
||||
|
||||
Quando um diretório de trabalho é definido, o AMP usa essa pasta para:
|
||||
|
||||
- Validação do projeto, incluindo `pyproject.toml`, arquivos de crew JSON e qualquer ponto de entrada clássico de Crew ou Flow
|
||||
- Instalação de dependências com `uv`
|
||||
- O diretório de trabalho do processo em execução
|
||||
- A variável de ambiente `CREW_ROOT_DIR`
|
||||
|
||||
Deixar o campo vazio mantém o comportamento existente e usa a raiz do
|
||||
repositório.
|
||||
|
||||
## Fontes Suportadas
|
||||
|
||||
Você pode definir um diretório de trabalho ao criar uma implantação a partir de:
|
||||
|
||||
- Um repositório GitHub conectado
|
||||
- Um repositório Git configurado no AMP
|
||||
- Um upload de ZIP
|
||||
|
||||
<Info>
|
||||
Configure diretórios de trabalho na interface web do AMP. O fluxo
|
||||
`crewai deploy create` da CLI não solicita esse campo.
|
||||
</Info>
|
||||
|
||||
Você também pode adicionar ou alterar o diretório de trabalho de uma implantação
|
||||
existente pela página **Settings** da implantação. A alteração passa a valer no
|
||||
próximo deploy.
|
||||
|
||||
<Warning>
|
||||
Diretórios de trabalho e auto-deploy não podem ser usados juntos. Se uma
|
||||
implantação tiver um diretório de trabalho, o auto-deploy fica desabilitado
|
||||
para ela. Desative o auto-deploy antes de definir um diretório de trabalho.
|
||||
</Warning>
|
||||
|
||||
## Configurar uma Nova Implantação
|
||||
|
||||
<Steps>
|
||||
<Step title="Abra Deploy from Code">
|
||||
No CrewAI AMP, crie uma nova implantação e escolha sua fonte: GitHub, Git
|
||||
Repository ou upload de ZIP.
|
||||
</Step>
|
||||
|
||||
<Step title="Selecione o repositório, branch ou arquivo ZIP">
|
||||
Escolha o repositório e a branch que contêm seu monorepo, ou envie um ZIP
|
||||
cuja raiz contenha os arquivos do monorepo.
|
||||
</Step>
|
||||
|
||||
<Step title="Abra as configurações avançadas">
|
||||
Expanda a seção **Advanced** no formulário de deploy.
|
||||
</Step>
|
||||
|
||||
<Step title="Informe o diretório de trabalho">
|
||||
Informe o caminho da raiz do repositório até o projeto Crew ou Flow:
|
||||
|
||||
```text
|
||||
crews/support_agent
|
||||
```
|
||||
|
||||
Não inclua uma barra inicial.
|
||||
</Step>
|
||||
|
||||
<Step title="Implante">
|
||||
Adicione as variáveis de ambiente necessárias e inicie a implantação.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Configurar uma Implantação Existente
|
||||
|
||||
<Steps>
|
||||
<Step title="Abra as configurações da implantação">
|
||||
Acesse sua automação no AMP e abra **Settings**.
|
||||
</Step>
|
||||
|
||||
<Step title="Desative o auto-deploy, se necessário">
|
||||
Se o auto-deploy estiver habilitado, desative-o primeiro. O campo de
|
||||
diretório de trabalho fica indisponível enquanto o auto-deploy está ativo.
|
||||
</Step>
|
||||
|
||||
<Step title="Defina o diretório de trabalho">
|
||||
Em **Basic settings**, informe o caminho da subpasta, como:
|
||||
|
||||
```text
|
||||
crews/support_agent
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Reimplante">
|
||||
Salve a configuração e reimplante a automação. O novo diretório de trabalho
|
||||
será usado no próximo deploy.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Regras de Caminho
|
||||
|
||||
O diretório de trabalho deve ser um caminho relativo dentro da raiz do
|
||||
repositório ou do ZIP.
|
||||
|
||||
| Regra | Exemplo |
|
||||
|-------|---------|
|
||||
| Use um caminho relativo | `crews/support_agent` |
|
||||
| Não comece com `/` | `/crews/support_agent` é inválido |
|
||||
| Não use segmentos de caminho `.` ou `..` | `crews/../support_agent` é inválido |
|
||||
| Use apenas letras, números, hifens, underscores, pontos e barras | `crews/support agent` é inválido |
|
||||
| Mantenha o caminho com 255 caracteres ou menos | Caminhos maiores são rejeitados |
|
||||
|
||||
O AMP remove espaços em branco no início e no fim, reduz barras repetidas e
|
||||
remove barras finais. Um valor em branco usa a raiz do repositório.
|
||||
|
||||
## Arquivos Lock e Workspaces UV
|
||||
|
||||
A pasta selecionada deve conter o `pyproject.toml` e os arquivos exigidos pelo
|
||||
tipo de projeto:
|
||||
|
||||
- Crew JSON-first: `crew.jsonc` ou `crew.json`, além de `agents/`
|
||||
- Crew clássico ou Flow: `src/` com o ponto de entrada Python esperado
|
||||
|
||||
Um arquivo `uv.lock` ou `poetry.lock` pode ficar na pasta selecionada ou na raiz
|
||||
do repositório.
|
||||
|
||||
Isso oferece suporte aos dois layouts comuns de arquivo lock:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Arquivo lock do projeto">
|
||||
```text
|
||||
company-ai/
|
||||
`-- crews/
|
||||
`-- support_agent/
|
||||
|-- pyproject.toml
|
||||
|-- uv.lock
|
||||
|-- crew.jsonc
|
||||
`-- agents/
|
||||
`-- support_agent.jsonc
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Arquivo lock do workspace">
|
||||
```text
|
||||
company-ai/
|
||||
|-- uv.lock
|
||||
|-- packages/
|
||||
| `-- shared_tools/
|
||||
`-- crews/
|
||||
`-- support_agent/
|
||||
|-- pyproject.toml
|
||||
|-- crew.jsonc
|
||||
`-- agents/
|
||||
`-- support_agent.jsonc
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
Se sua automação importar pacotes compartilhados de outro lugar do monorepo,
|
||||
declare esses pacotes no `pyproject.toml` usando configuração de workspace,
|
||||
caminho ou source do UV. O AMP executa a automação a partir da pasta
|
||||
selecionada, então o código compartilhado deve ser instalado como dependência
|
||||
em vez de depender da raiz do repositório no Python path.
|
||||
</Tip>
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Diretório de Trabalho Não Encontrado
|
||||
|
||||
Verifique se o caminho é relativo à raiz do repositório ou do ZIP. Para uploads
|
||||
de ZIP, o conteúdo do ZIP deve incluir exatamente o caminho informado como
|
||||
diretório de trabalho.
|
||||
|
||||
### pyproject.toml Ausente
|
||||
|
||||
O diretório de trabalho deve apontar para a pasta do projeto Crew ou Flow, não
|
||||
apenas para uma pasta pai que contém vários projetos.
|
||||
|
||||
### uv.lock ou poetry.lock Ausente
|
||||
|
||||
Faça commit de um arquivo lock na pasta do projeto selecionada ou na raiz do
|
||||
repositório. Para workspaces UV, manter `uv.lock` na raiz do workspace é
|
||||
suportado.
|
||||
|
||||
### Auto-Deploy Indisponível
|
||||
|
||||
O auto-deploy fica desabilitado enquanto um diretório de trabalho está definido.
|
||||
Use reimplantações manuais ou acione reimplantações a partir de CI/CD com a API
|
||||
do AMP.
|
||||
|
||||
<Card title="Deploy para AMP" icon="rocket" href="/pt-BR/enterprise/guides/deploy-to-amp">
|
||||
Continue com o guia de implantação depois de escolher o diretório de trabalho
|
||||
do monorepo.
|
||||
</Card>
|
||||
69
docs/edge/pt-BR/enterprise/guides/onedrive-trigger.mdx
Normal file
69
docs/edge/pt-BR/enterprise/guides/onedrive-trigger.mdx
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: "OneDrive Trigger"
|
||||
description: "Automate responses to OneDrive file activity"
|
||||
icon: "cloud"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Start automations when files change inside OneDrive. You can generate audit summaries, notify security teams about external sharing, or update downstream line-of-business systems with new document metadata.
|
||||
|
||||
<Tip>
|
||||
Connect OneDrive in **Tools & Integrations** and toggle the trigger on for
|
||||
your deployment.
|
||||
</Tip>
|
||||
|
||||
## Enabling the OneDrive Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **OneDrive** and switch the toggle to enable
|
||||
|
||||
<Frame caption="Microsoft OneDrive trigger connection">
|
||||
<img
|
||||
src="/images/enterprise/onedrive-trigger.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Audit file permissions
|
||||
|
||||
```python
|
||||
from onedrive_file_crew import OneDriveFileTrigger
|
||||
|
||||
crew = OneDriveFileTrigger().crew()
|
||||
crew.kickoff({
|
||||
"crewai_trigger_payload": onedrive_payload,
|
||||
})
|
||||
```
|
||||
|
||||
The crew inspects file metadata, user activity, and permission changes to produce a compliance-friendly summary.
|
||||
|
||||
## Testando Localmente
|
||||
|
||||
Teste sua integração de trigger do OneDrive localmente usando a CLI da CrewAI:
|
||||
|
||||
```bash
|
||||
# Visualize todos os triggers disponíveis
|
||||
crewai triggers list
|
||||
|
||||
# Simule um trigger do OneDrive com payload realista
|
||||
crewai triggers run microsoft_onedrive/file_changed
|
||||
```
|
||||
|
||||
O comando `crewai triggers run` executará sua crew com um payload completo do OneDrive, permitindo que você teste sua lógica de parsing antes do deployment.
|
||||
|
||||
<Warning>
|
||||
Use `crewai triggers run microsoft_onedrive/file_changed` (não `crewai run`)
|
||||
para simular execução de trigger durante o desenvolvimento. Após o deployment,
|
||||
sua crew receberá automaticamente o payload do trigger.
|
||||
</Warning>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Ensure the connected account has permission to read the file metadata included in the webhook
|
||||
- Teste localmente com `crewai triggers run microsoft_onedrive/file_changed` para ver a estrutura exata do payload
|
||||
- If the trigger fires but the payload is missing `permissions`, confirm the site-level sharing settings allow Graph to return this field
|
||||
- For large tenants, filter notifications upstream so the crew only runs on relevant directories
|
||||
- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger
|
||||
69
docs/edge/pt-BR/enterprise/guides/outlook-trigger.mdx
Normal file
69
docs/edge/pt-BR/enterprise/guides/outlook-trigger.mdx
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: "Outlook Trigger"
|
||||
description: "Launch automations from Outlook emails and calendar updates"
|
||||
icon: "microsoft"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Automate responses when Outlook delivers a new message or when an event is removed from the calendar. Teams commonly route escalations, file tickets, or alert attendees of cancellations.
|
||||
|
||||
<Tip>
|
||||
Connect Outlook in **Tools & Integrations** and ensure the trigger is enabled
|
||||
for your deployment.
|
||||
</Tip>
|
||||
|
||||
## Enabling the Outlook Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **Outlook** and switch the toggle to enable
|
||||
|
||||
<Frame caption="Microsoft Outlook trigger connection">
|
||||
<img
|
||||
src="/images/enterprise/outlook-trigger.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Summarize a new email
|
||||
|
||||
```python
|
||||
from outlook_message_crew import OutlookMessageTrigger
|
||||
|
||||
crew = OutlookMessageTrigger().crew()
|
||||
crew.kickoff({
|
||||
"crewai_trigger_payload": outlook_payload,
|
||||
})
|
||||
```
|
||||
|
||||
The crew extracts sender details, subject, body preview, and attachments before generating a structured response.
|
||||
|
||||
## Testando Localmente
|
||||
|
||||
Teste sua integração de trigger do Outlook localmente usando a CLI da CrewAI:
|
||||
|
||||
```bash
|
||||
# Visualize todos os triggers disponíveis
|
||||
crewai triggers list
|
||||
|
||||
# Simule um trigger do Outlook com payload realista
|
||||
crewai triggers run microsoft_outlook/email_received
|
||||
```
|
||||
|
||||
O comando `crewai triggers run` executará sua crew com um payload completo do Outlook, permitindo que você teste sua lógica de parsing antes do deployment.
|
||||
|
||||
<Warning>
|
||||
Use `crewai triggers run microsoft_outlook/email_received` (não `crewai run`)
|
||||
para simular execução de trigger durante o desenvolvimento. Após o deployment,
|
||||
sua crew receberá automaticamente o payload do trigger.
|
||||
</Warning>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Verify the Outlook connector is still authorized; the subscription must be renewed periodically
|
||||
- Teste localmente com `crewai triggers run microsoft_outlook/email_received` para ver a estrutura exata do payload
|
||||
- If attachments are missing, confirm the webhook subscription includes the `includeResourceData` flag
|
||||
- Review execution logs when events fail to match—cancellation payloads lack attendee lists by design and the crew should account for that
|
||||
- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger
|
||||
345
docs/edge/pt-BR/enterprise/guides/prepare-for-deployment.mdx
Normal file
345
docs/edge/pt-BR/enterprise/guides/prepare-for-deployment.mdx
Normal file
@@ -0,0 +1,345 @@
|
||||
---
|
||||
title: "Preparar para Implantação"
|
||||
description: "Certifique-se de que seu Crew ou Flow está pronto para implantação no CrewAI AMP"
|
||||
icon: "clipboard-check"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Antes de implantar no CrewAI AMP, é crucial verificar se seu projeto está estruturado corretamente.
|
||||
Tanto Crews quanto Flows podem ser implantados como "automações", mas eles têm estruturas de projeto
|
||||
e requisitos diferentes que devem ser atendidos para uma implantação bem-sucedida.
|
||||
</Note>
|
||||
|
||||
## Entendendo Automações
|
||||
|
||||
No CrewAI AMP, **automações** é o termo geral para projetos de IA Agêntica implantáveis. Uma automação pode ser:
|
||||
|
||||
- **Um Crew**: Uma equipe independente de agentes de IA trabalhando juntos em tarefas
|
||||
- **Um Flow**: Um workflow orquestrado que pode combinar múltiplos crews, chamadas diretas de LLM e lógica procedural
|
||||
|
||||
Entender qual tipo você está implantando é essencial porque eles têm estruturas de projeto e pontos de entrada diferentes.
|
||||
|
||||
## Crews vs Flows: Principais Diferenças
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Projetos Crew" icon="users">
|
||||
Equipes independentes de agentes de IA. Novas crews são JSON-first com `crew.jsonc` e `agents/`; crews clássicas ainda podem usar `crew.py`.
|
||||
</Card>
|
||||
<Card title="Projetos Flow" icon="diagram-project">
|
||||
Workflows orquestrados com crews embutidos em uma pasta `crews/`. Ideal para processos complexos de múltiplas etapas.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
| Aspecto | Crew | Flow |
|
||||
|---------|------|------|
|
||||
| **Estrutura do projeto** | Raiz do projeto com `crew.jsonc` e `agents/` | `src/project_name/` com pasta `crews/` |
|
||||
| **Localização da lógica principal** | `crew.jsonc` (clássico: `src/project_name/crew.py`) | `src/project_name/main.py` (classe Flow) |
|
||||
| **Função de ponto de entrada** | Carregada a partir de `crew.jsonc` (clássico: `run()` em `main.py`) | `kickoff()` em `main.py` |
|
||||
| **Tipo no pyproject.toml** | `type = "crew"` | `type = "flow"` |
|
||||
| **Comando CLI de criação** | `crewai create crew name` | `crewai create flow name` |
|
||||
| **Localização da configuração** | `crew.jsonc`, `agents/`, `tools/` opcional | `src/project_name/crews/crew_name/config/` ou pastas de crew JSON embutidas |
|
||||
| **Pode conter outros crews** | Não | Sim (na pasta `crews/`) |
|
||||
|
||||
## Referência de Estrutura de Projeto
|
||||
|
||||
### Estrutura de Projeto Crew
|
||||
|
||||
Quando você executa `crewai create crew my_crew`, recebe a estrutura JSON-first:
|
||||
|
||||
```
|
||||
my_crew/
|
||||
├── .gitignore
|
||||
├── pyproject.toml # Deve ter type = "crew"
|
||||
├── README.md
|
||||
├── .env
|
||||
├── uv.lock # OBRIGATÓRIO para implantação
|
||||
├── crew.jsonc # Configurações, tarefas, processo e inputs
|
||||
├── agents/
|
||||
│ └── researcher.jsonc # Definições de agentes
|
||||
├── tools/ # Ferramentas custom:<name> opcionais
|
||||
├── knowledge/
|
||||
└── skills/
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Para crews JSON-first, mantenha `crew.jsonc`, `agents/`, `tools/`, `knowledge/` e `skills/`
|
||||
na raiz do projeto. Colocá-los dentro de `src/` impede que `crewai run` e a validação de
|
||||
implantação encontrem a definição da crew.
|
||||
</Warning>
|
||||
|
||||
<Info>
|
||||
Projetos clássicos criados com `crewai create crew my_crew --classic` usam a estrutura antiga
|
||||
`src/project_name/crew.py`, `src/project_name/config/agents.yaml` e
|
||||
`src/project_name/config/tasks.yaml`. Essa estrutura continua suportada para crews Python com decorators.
|
||||
</Info>
|
||||
|
||||
### Estrutura de Projeto Flow
|
||||
|
||||
Quando você executa `crewai create flow my_flow`, você obtém esta estrutura:
|
||||
|
||||
```
|
||||
my_flow/
|
||||
├── .gitignore
|
||||
├── pyproject.toml # Deve ter type = "flow"
|
||||
├── README.md
|
||||
├── .env
|
||||
├── uv.lock # OBRIGATÓRIO para implantação
|
||||
└── src/
|
||||
└── my_flow/
|
||||
├── __init__.py
|
||||
├── main.py # Ponto de entrada com função kickoff() + classe Flow
|
||||
├── crews/ # Pasta de crews embutidos
|
||||
│ └── poem_crew/
|
||||
│ ├── __init__.py
|
||||
│ ├── poem_crew.py # Crew com decorador @CrewBase
|
||||
│ └── config/
|
||||
│ ├── agents.yaml
|
||||
│ └── tasks.yaml
|
||||
└── tools/
|
||||
├── __init__.py
|
||||
└── custom_tool.py
|
||||
```
|
||||
|
||||
<Info>
|
||||
Crews independentes JSON-first usam arquivos JSON na raiz do projeto. Flows ainda usam
|
||||
`src/project_name/` e podem conter crews embutidas clássicas ou pastas de crew JSON carregadas com
|
||||
`crewai.project.load_crew`.
|
||||
</Info>
|
||||
|
||||
## Checklist Pré-Implantação
|
||||
|
||||
Use este checklist para verificar se seu projeto está pronto para implantação.
|
||||
|
||||
### 1. Verificar Configuração do pyproject.toml
|
||||
|
||||
Seu `pyproject.toml` deve incluir a seção `[tool.crewai]` correta:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Para Crews">
|
||||
```toml
|
||||
[tool.crewai]
|
||||
type = "crew"
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Para Flows">
|
||||
```toml
|
||||
[tool.crewai]
|
||||
type = "flow"
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Warning>
|
||||
Se o `type` não corresponder à estrutura do seu projeto, o build falhará ou
|
||||
a automação não funcionará corretamente.
|
||||
</Warning>
|
||||
|
||||
### 2. Garantir que o Arquivo uv.lock Existe
|
||||
|
||||
CrewAI usa `uv` para gerenciamento de dependências. O arquivo `uv.lock` garante builds reproduzíveis e é **obrigatório** para implantação.
|
||||
|
||||
```bash
|
||||
# Gerar ou atualizar o arquivo lock
|
||||
uv lock
|
||||
|
||||
# Verificar se existe
|
||||
ls -la uv.lock
|
||||
```
|
||||
|
||||
Se o arquivo não existir, execute `uv lock` e faça commit no seu repositório:
|
||||
|
||||
```bash
|
||||
uv lock
|
||||
git add uv.lock
|
||||
git commit -m "Add uv.lock for deployment"
|
||||
git push
|
||||
```
|
||||
|
||||
### 3. Validar a Definição da Crew
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Crews JSON-first">
|
||||
Crews JSON-first precisam ter `crew.jsonc` ou `crew.json` na raiz do projeto.
|
||||
O array `agents` deve apontar para arquivos em `agents/`, e cada task deve referenciar
|
||||
um nome de agent válido.
|
||||
|
||||
```jsonc crew.jsonc
|
||||
{
|
||||
"name": "Research Crew",
|
||||
"agents": ["researcher"],
|
||||
"tasks": [
|
||||
{
|
||||
"name": "research_task",
|
||||
"description": "Research {topic}.",
|
||||
"expected_output": "A concise report.",
|
||||
"agent": "researcher"
|
||||
}
|
||||
],
|
||||
"inputs": {
|
||||
"topic": "AI Agents"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Ferramentas customizadas são referenciadas como `"custom:<name>"` e devem existir em
|
||||
`tools/<name>.py` com uma subclasse de `BaseTool`.
|
||||
</Tab>
|
||||
<Tab title="Crews Python/YAML Clássicas">
|
||||
Crews clássicas e crews Python embutidas em Flows devem usar o decorador `@CrewBase`.
|
||||
|
||||
```python
|
||||
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 MyCrew():
|
||||
"""Descrição do meu crew"""
|
||||
|
||||
agents: List[BaseAgent]
|
||||
tasks: List[Task]
|
||||
|
||||
@agent
|
||||
def my_agent(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['my_agent'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
@task
|
||||
def my_task(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['my_task'] # type: ignore[index]
|
||||
)
|
||||
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
verbose=True,
|
||||
)
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### 4. Verificar Pontos de Entrada do Projeto
|
||||
|
||||
Crews JSON-first independentes não precisam de um `src/project_name/main.py` escrito manualmente;
|
||||
`crewai run` e o empacotamento de implantação carregam `crew.jsonc` diretamente. Crews clássicas e Flows usam pontos de entrada Python:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Crews JSON-first">
|
||||
Execute localmente a partir da raiz do projeto:
|
||||
|
||||
```bash
|
||||
crewai run
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Crews Clássicas">
|
||||
O ponto de entrada usa uma função `run()`:
|
||||
|
||||
```python
|
||||
# src/my_crew/main.py
|
||||
from my_crew.crew import MyCrew
|
||||
|
||||
def run():
|
||||
"""Executa o crew."""
|
||||
inputs = {'topic': 'AI in Healthcare'}
|
||||
result = MyCrew().crew().kickoff(inputs=inputs)
|
||||
return result
|
||||
|
||||
if __name__ == "__main__":
|
||||
run()
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Para Flows">
|
||||
O ponto de entrada usa uma função `kickoff()` com uma classe Flow:
|
||||
|
||||
```python
|
||||
# src/my_flow/main.py
|
||||
from crewai.flow import Flow, listen, start
|
||||
from my_flow.crews.poem_crew.poem_crew import PoemCrew
|
||||
|
||||
class MyFlow(Flow):
|
||||
@start()
|
||||
def begin(self):
|
||||
# Lógica do Flow aqui
|
||||
result = PoemCrew().crew().kickoff(inputs={...})
|
||||
return result
|
||||
|
||||
def kickoff():
|
||||
"""Executa o flow."""
|
||||
MyFlow().kickoff()
|
||||
|
||||
if __name__ == "__main__":
|
||||
kickoff()
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### 5. Preparar Variáveis de Ambiente
|
||||
|
||||
Antes da implantação, certifique-se de ter:
|
||||
|
||||
1. **Chaves de API de LLM** prontas (OpenAI, Anthropic, Google, etc.)
|
||||
2. **Chaves de API de ferramentas** se estiver usando ferramentas externas (Serper, etc.)
|
||||
|
||||
<Info>
|
||||
Se seu projeto depende de pacotes de um **registro PyPI privado**, você também precisará configurar
|
||||
credenciais de autenticação do registro como variáveis de ambiente. Consulte o guia
|
||||
[Registros de Pacotes Privados](/pt-BR/enterprise/guides/private-package-registry) para mais detalhes.
|
||||
</Info>
|
||||
|
||||
<Tip>
|
||||
Teste seu projeto localmente com as mesmas variáveis de ambiente antes de implantar
|
||||
para detectar problemas de configuração antecipadamente.
|
||||
</Tip>
|
||||
|
||||
## Comandos de Validação Rápida
|
||||
|
||||
Execute estes comandos a partir da raiz do seu projeto para verificar rapidamente sua configuração:
|
||||
|
||||
```bash
|
||||
# 1. Verificar tipo do projeto no pyproject.toml
|
||||
grep -A2 "\[tool.crewai\]" pyproject.toml
|
||||
|
||||
# 2. Verificar se uv.lock existe
|
||||
ls -la uv.lock || echo "ERRO: uv.lock ausente! Execute 'uv lock'"
|
||||
|
||||
# 3. Para crews JSON-first, verificar crew.jsonc e agents/
|
||||
([ -f crew.jsonc ] || [ -f crew.json ]) || echo "Nenhum crew.jsonc ou crew.json encontrado"
|
||||
test -d agents || echo "Nenhum diretório agents/ encontrado"
|
||||
|
||||
# 4. Para Crews clássicas - verificar se crew.py existe
|
||||
ls -la src/*/crew.py 2>/dev/null || echo "Nenhum crew.py (esperado para Crews)"
|
||||
|
||||
# 5. Para Flows - verificar se pasta crews/ existe
|
||||
ls -la src/*/crews/ 2>/dev/null || echo "Nenhuma pasta crews/ (esperado para Flows)"
|
||||
|
||||
# 6. Para crews Python clássicas - verificar uso do CrewBase
|
||||
grep -r "@CrewBase" . --include="*.py"
|
||||
```
|
||||
|
||||
## Erros Comuns de Configuração
|
||||
|
||||
| Erro | Sintoma | Correção |
|
||||
|------|---------|----------|
|
||||
| `uv.lock` ausente | Build falha durante resolução de dependências | Execute `uv lock` e faça commit |
|
||||
| `type` errado no pyproject.toml | Build bem-sucedido mas falha em runtime | Altere para o tipo correto |
|
||||
| `crew.jsonc` ou `agents/` ausente em uma crew JSON-first | Definição da crew não encontrada | Mantenha `crew.jsonc` e `agents/` na raiz do projeto |
|
||||
| Decorador `@CrewBase` ausente em uma crew clássica | Erros "Config not found" | Adicione o decorador a todas as classes crew clássicas |
|
||||
| Arquivos clássicos na raiz ao invés de `src/` | Ponto de entrada não encontrado | Mova arquivos Python clássicos para `src/project_name/` |
|
||||
| `run()` ou `kickoff()` ausente | Não é possível iniciar automação | Adicione a função de entrada correta |
|
||||
|
||||
## Próximos Passos
|
||||
|
||||
Uma vez que seu projeto passar por todos os itens do checklist, você está pronto para implantar:
|
||||
|
||||
<Card title="Deploy para AMP" icon="rocket" href="/pt-BR/enterprise/guides/deploy-to-amp">
|
||||
Siga o guia de implantação para implantar seu Crew ou Flow no CrewAI AMP usando
|
||||
a CLI, interface web ou integração CI/CD.
|
||||
</Card>
|
||||
263
docs/edge/pt-BR/enterprise/guides/private-package-registry.mdx
Normal file
263
docs/edge/pt-BR/enterprise/guides/private-package-registry.mdx
Normal file
@@ -0,0 +1,263 @@
|
||||
---
|
||||
title: "Registros de Pacotes Privados"
|
||||
description: "Instale pacotes Python privados de registros PyPI autenticados no CrewAI AMP"
|
||||
icon: "lock"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Este guia aborda como configurar seu projeto CrewAI para instalar pacotes Python
|
||||
de registros PyPI privados (Azure DevOps Artifacts, GitHub Packages, GitLab, AWS CodeArtifact, etc.)
|
||||
ao implantar no CrewAI AMP.
|
||||
</Note>
|
||||
|
||||
## Quando Você Precisa Disso
|
||||
|
||||
Se seu projeto depende de pacotes Python internos ou proprietários hospedados em um registro privado
|
||||
em vez do PyPI público, você precisará:
|
||||
|
||||
1. Informar ao UV **onde** encontrar o pacote (uma URL de index)
|
||||
2. Informar ao UV **quais** pacotes vêm desse index (um mapeamento de source)
|
||||
3. Fornecer **credenciais** para que o UV possa autenticar durante a instalação
|
||||
|
||||
O CrewAI AMP usa [UV](https://docs.astral.sh/uv/) para resolução e instalação de dependências.
|
||||
O UV suporta registros privados autenticados por meio da configuração do `pyproject.toml` combinada
|
||||
com variáveis de ambiente para credenciais.
|
||||
|
||||
## Passo 1: Configurar o pyproject.toml
|
||||
|
||||
Três elementos trabalham juntos no seu `pyproject.toml`:
|
||||
|
||||
### 1a. Declarar a dependência
|
||||
|
||||
Adicione o pacote privado ao seu `[project.dependencies]` como qualquer outra dependência:
|
||||
|
||||
```toml
|
||||
[project]
|
||||
dependencies = [
|
||||
"crewai[tools]>=0.100.1,<1.0.0",
|
||||
"my-private-package>=1.2.0",
|
||||
]
|
||||
```
|
||||
|
||||
### 1b. Definir o index
|
||||
|
||||
Registre seu registro privado como um index nomeado em `[[tool.uv.index]]`:
|
||||
|
||||
```toml
|
||||
[[tool.uv.index]]
|
||||
name = "my-private-registry"
|
||||
url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
|
||||
explicit = true
|
||||
```
|
||||
|
||||
<Info>
|
||||
O campo `name` é importante — o UV o utiliza para construir os nomes das variáveis de ambiente
|
||||
para autenticação (veja o [Passo 2](#passo-2-configurar-credenciais-de-autenticação) abaixo).
|
||||
|
||||
Definir `explicit = true` significa que o UV não consultará esse index para todos os pacotes — apenas
|
||||
os que você mapear explicitamente em `[tool.uv.sources]`. Isso evita consultas desnecessárias
|
||||
ao seu registro privado e protege contra ataques de confusão de dependências.
|
||||
</Info>
|
||||
|
||||
### 1c. Mapear o pacote para o index
|
||||
|
||||
Informe ao UV quais pacotes devem ser resolvidos a partir do seu index privado usando `[tool.uv.sources]`:
|
||||
|
||||
```toml
|
||||
[tool.uv.sources]
|
||||
my-private-package = { index = "my-private-registry" }
|
||||
```
|
||||
|
||||
### Exemplo completo
|
||||
|
||||
```toml
|
||||
[project]
|
||||
name = "my-crew-project"
|
||||
version = "0.1.0"
|
||||
requires-python = ">=3.10,<=3.13"
|
||||
dependencies = [
|
||||
"crewai[tools]>=0.100.1,<1.0.0",
|
||||
"my-private-package>=1.2.0",
|
||||
]
|
||||
|
||||
[tool.crewai]
|
||||
type = "crew"
|
||||
|
||||
[[tool.uv.index]]
|
||||
name = "my-private-registry"
|
||||
url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
|
||||
explicit = true
|
||||
|
||||
[tool.uv.sources]
|
||||
my-private-package = { index = "my-private-registry" }
|
||||
```
|
||||
|
||||
Após atualizar o `pyproject.toml`, regenere seu arquivo lock:
|
||||
|
||||
```bash
|
||||
uv lock
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Sempre faça commit do `uv.lock` atualizado junto com as alterações no `pyproject.toml`.
|
||||
O arquivo lock é obrigatório para implantação — veja [Preparar para Implantação](/pt-BR/enterprise/guides/prepare-for-deployment).
|
||||
</Warning>
|
||||
|
||||
## Passo 2: Configurar Credenciais de Autenticação
|
||||
|
||||
O UV autentica em indexes privados usando variáveis de ambiente que seguem uma convenção de nomenclatura
|
||||
baseada no nome do index que você definiu no `pyproject.toml`:
|
||||
|
||||
```
|
||||
UV_INDEX_{UPPER_NAME}_USERNAME
|
||||
UV_INDEX_{UPPER_NAME}_PASSWORD
|
||||
```
|
||||
|
||||
Onde `{UPPER_NAME}` é o nome do seu index convertido para **maiúsculas** com **hifens substituídos por underscores**.
|
||||
|
||||
Por exemplo, um index chamado `my-private-registry` usa:
|
||||
|
||||
| Variável | Valor |
|
||||
|----------|-------|
|
||||
| `UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME` | Seu nome de usuário ou nome do token do registro |
|
||||
| `UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD` | Sua senha ou token/PAT do registro |
|
||||
|
||||
<Warning>
|
||||
Essas variáveis de ambiente **devem** ser adicionadas pelas configurações de **Variáveis de Ambiente** do CrewAI AMP —
|
||||
globalmente ou no nível da implantação. Elas não podem ser definidas em arquivos `.env` ou codificadas no seu projeto.
|
||||
|
||||
Veja [Configurar Variáveis de Ambiente no AMP](#configurar-variáveis-de-ambiente-no-amp) abaixo.
|
||||
</Warning>
|
||||
|
||||
## Referência de Provedores de Registro
|
||||
|
||||
A tabela abaixo mostra o formato da URL de index e os valores de credenciais para provedores de registro comuns.
|
||||
Substitua os valores de exemplo pelos detalhes reais da sua organização e feed.
|
||||
|
||||
| Provedor | URL do Index | Usuário | Senha |
|
||||
|----------|-------------|---------|-------|
|
||||
| **Azure DevOps Artifacts** | `https://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/` | Qualquer string não vazia (ex: `token`) | Personal Access Token (PAT) com escopo Packaging Read |
|
||||
| **GitHub Packages** | `https://pypi.pkg.github.com/{owner}/simple/` | Nome de usuário do GitHub | Personal Access Token (classic) com escopo `read:packages` |
|
||||
| **GitLab Package Registry** | `https://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/` | `__token__` | Project ou Personal Access Token com escopo `read_api` |
|
||||
| **AWS CodeArtifact** | Use a URL de `aws codeartifact get-repository-endpoint` | `aws` | Token de `aws codeartifact get-authorization-token` |
|
||||
| **Google Artifact Registry** | `https://{region}-python.pkg.dev/{project}/{repo}/simple/` | `_json_key_base64` | Chave de conta de serviço codificada em Base64 |
|
||||
| **JFrog Artifactory** | `https://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/` | Nome de usuário ou email | Chave API ou token de identidade |
|
||||
| **Auto-hospedado (devpi, Nexus, etc.)** | URL da API simple do seu registro | Nome de usuário do registro | Senha do registro |
|
||||
|
||||
<Tip>
|
||||
Para **AWS CodeArtifact**, o token de autorização expira periodicamente.
|
||||
Você precisará atualizar o valor de `UV_INDEX_*_PASSWORD` quando ele expirar.
|
||||
Considere automatizar isso no seu pipeline de CI/CD.
|
||||
</Tip>
|
||||
|
||||
## Configurar Variáveis de Ambiente no AMP
|
||||
|
||||
As credenciais do registro privado devem ser configuradas como variáveis de ambiente no CrewAI AMP.
|
||||
Você tem duas opções:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Interface Web">
|
||||
1. Faça login no [CrewAI AMP](https://app.crewai.com)
|
||||
2. Navegue até sua automação
|
||||
3. Abra a aba **Environment Variables**
|
||||
4. Adicione cada variável (`UV_INDEX_*_USERNAME` e `UV_INDEX_*_PASSWORD`) com seu valor
|
||||
|
||||
Veja o passo [Deploy para AMP — Definir Variáveis de Ambiente](/pt-BR/enterprise/guides/deploy-to-amp#definir-as-variáveis-de-ambiente) para detalhes.
|
||||
</Tab>
|
||||
<Tab title="Implantação via CLI">
|
||||
Adicione as variáveis ao seu arquivo `.env` local antes de executar `crewai deploy create`.
|
||||
A CLI as transferirá com segurança para a plataforma:
|
||||
|
||||
```bash
|
||||
# .env
|
||||
OPENAI_API_KEY=sk-...
|
||||
UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
|
||||
UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here
|
||||
```
|
||||
|
||||
```bash
|
||||
crewai deploy create
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Warning>
|
||||
**Nunca** faça commit de credenciais no seu repositório. Use variáveis de ambiente do AMP para todos os segredos.
|
||||
O arquivo `.env` deve estar listado no `.gitignore`.
|
||||
</Warning>
|
||||
|
||||
Para atualizar credenciais em uma implantação existente, veja [Atualizar Seu Crew — Variáveis de Ambiente](/pt-BR/enterprise/guides/update-crew).
|
||||
|
||||
## Como Tudo se Conecta
|
||||
|
||||
Quando o CrewAI AMP faz o build da sua automação, o fluxo de resolução funciona assim:
|
||||
|
||||
<Steps>
|
||||
<Step title="Build inicia">
|
||||
O AMP busca seu repositório e lê o `pyproject.toml` e o `uv.lock`.
|
||||
</Step>
|
||||
<Step title="UV resolve dependências">
|
||||
O UV lê `[tool.uv.sources]` para determinar de qual index cada pacote deve vir.
|
||||
</Step>
|
||||
<Step title="UV autentica">
|
||||
Para cada index privado, o UV busca `UV_INDEX_{NAME}_USERNAME` e `UV_INDEX_{NAME}_PASSWORD`
|
||||
nas variáveis de ambiente que você configurou no AMP.
|
||||
</Step>
|
||||
<Step title="Pacotes são instalados">
|
||||
O UV baixa e instala todos os pacotes — tanto públicos (do PyPI) quanto privados (do seu registro).
|
||||
</Step>
|
||||
<Step title="Automação executa">
|
||||
Seu crew ou flow inicia com todas as dependências disponíveis.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Erros de Autenticação Durante o Build
|
||||
|
||||
**Sintoma**: Build falha com `401 Unauthorized` ou `403 Forbidden` ao resolver um pacote privado.
|
||||
|
||||
**Verifique**:
|
||||
- Os nomes das variáveis de ambiente `UV_INDEX_*` correspondem exatamente ao nome do seu index (maiúsculas, hifens -> underscores)
|
||||
- As credenciais estão definidas nas variáveis de ambiente do AMP, não apenas em um `.env` local
|
||||
- Seu token/PAT tem as permissões de leitura necessárias para o feed de pacotes
|
||||
- O token não expirou (especialmente relevante para AWS CodeArtifact)
|
||||
|
||||
### Pacote Não Encontrado
|
||||
|
||||
**Sintoma**: `No matching distribution found for my-private-package`.
|
||||
|
||||
**Verifique**:
|
||||
- A URL do index no `pyproject.toml` termina com `/simple/`
|
||||
- A entrada `[tool.uv.sources]` mapeia o nome correto do pacote para o nome correto do index
|
||||
- O pacote está realmente publicado no seu registro privado
|
||||
- Execute `uv lock` localmente com as mesmas credenciais para verificar se a resolução funciona
|
||||
|
||||
### Conflitos no Arquivo Lock
|
||||
|
||||
**Sintoma**: `uv lock` falha ou produz resultados inesperados após adicionar um index privado.
|
||||
|
||||
**Solução**: Defina as credenciais localmente e regenere:
|
||||
|
||||
```bash
|
||||
export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
|
||||
export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat
|
||||
uv lock
|
||||
```
|
||||
|
||||
Em seguida, faça commit do `uv.lock` atualizado.
|
||||
|
||||
## Guias Relacionados
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Preparar para Implantação" icon="clipboard-check" href="/pt-BR/enterprise/guides/prepare-for-deployment">
|
||||
Verifique a estrutura do projeto e as dependências antes de implantar.
|
||||
</Card>
|
||||
<Card title="Deploy para AMP" icon="rocket" href="/pt-BR/enterprise/guides/deploy-to-amp">
|
||||
Implante seu crew ou flow e configure variáveis de ambiente.
|
||||
</Card>
|
||||
<Card title="Atualizar Seu Crew" icon="arrows-rotate" href="/pt-BR/enterprise/guides/update-crew">
|
||||
Atualize variáveis de ambiente e envie alterações para uma implantação em execução.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
112
docs/edge/pt-BR/enterprise/guides/react-component-export.mdx
Normal file
112
docs/edge/pt-BR/enterprise/guides/react-component-export.mdx
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: "Exportação de Componentes React"
|
||||
description: "Aprenda como exportar e integrar componentes React do CrewAI AMP em suas aplicações"
|
||||
icon: "react"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
Este guia explica como exportar crews do CrewAI AMP 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
|
||||
50
docs/edge/pt-BR/enterprise/guides/salesforce-trigger.mdx
Normal file
50
docs/edge/pt-BR/enterprise/guides/salesforce-trigger.mdx
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: "Trigger Salesforce"
|
||||
description: "Dispare equipes CrewAI a partir de fluxos de trabalho do Salesforce para automação de CRM"
|
||||
icon: "salesforce"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
A CrewAI AMP 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
|
||||
|
||||
<iframe
|
||||
className="w-full aspect-video rounded-xl"
|
||||
src="https://www.youtube.com/embed/oJunVqjjfu4"
|
||||
title="Demonstração de trigger CrewAI + Salesforce"
|
||||
frameBorder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowFullScreen
|
||||
></iframe>
|
||||
|
||||
## Primeiros Passos
|
||||
|
||||
Para configurar triggers no Salesforce:
|
||||
|
||||
1. **Contato com o Suporte**: Entre em contato com o suporte da CrewAI AMP 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 AMP, que pode fornecer orientações personalizadas para o seu ambiente Salesforce e necessidades de negócio.
|
||||
62
docs/edge/pt-BR/enterprise/guides/slack-trigger.mdx
Normal file
62
docs/edge/pt-BR/enterprise/guides/slack-trigger.mdx
Normal file
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: "Slack Trigger"
|
||||
description: "Acione crews do CrewAI diretamente do Slack usando comandos de barra"
|
||||
icon: "slack"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
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.
|
||||
106
docs/edge/pt-BR/enterprise/guides/team-management.mdx
Normal file
106
docs/edge/pt-BR/enterprise/guides/team-management.mdx
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: "Gestão de Equipes"
|
||||
description: "Aprenda como convidar e gerenciar membros da equipe em sua organização CrewAI AMP"
|
||||
icon: "users"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
Como administrador de uma conta CrewAI AMP, 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 AMP - 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 AMP - 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 AMP.
|
||||
109
docs/edge/pt-BR/enterprise/guides/tool-repository.mdx
Normal file
109
docs/edge/pt-BR/enterprise/guides/tool-repository.mdx
Normal file
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: Repositório de Ferramentas
|
||||
description: "Usando o Repositório de Ferramentas para gerenciar suas ferramentas"
|
||||
icon: "toolbox"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 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 AMP](https://app.crewai.com)
|
||||
- [CrewAI CLI](/pt-BR/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 AMP
|
||||
|
||||
## Instalando ferramentas
|
||||
|
||||
Para instalar uma ferramenta:
|
||||
|
||||
```bash
|
||||
crewai tool install <nome-da-ferramenta>
|
||||
```
|
||||
|
||||
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 <nome-da-ferramenta>
|
||||
```
|
||||
|
||||
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](/pt-BR/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 "Atualizar versão para 0.1.1"
|
||||
crewai tool publish
|
||||
```
|
||||
|
||||
## Excluindo ferramentas
|
||||
|
||||
Para excluir uma ferramenta:
|
||||
|
||||
1. Acesse o [CrewAI AMP](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 AMP > 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>
|
||||
132
docs/edge/pt-BR/enterprise/guides/training-crews.mdx
Normal file
132
docs/edge/pt-BR/enterprise/guides/training-crews.mdx
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
title: "Treinamento de Crews"
|
||||
description: "Treine seus crews implantados diretamente da plataforma CrewAI AMP para melhorar o desempenho dos agentes ao longo do tempo"
|
||||
icon: "dumbbell"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
O treinamento permite que você melhore o desempenho do crew executando sessões de treinamento iterativas diretamente da aba **Training** no CrewAI AMP. A plataforma usa o **modo de auto-treinamento** — ela gerencia o processo iterativo automaticamente, diferente do treinamento via CLI que requer feedback humano interativo por iteração.
|
||||
|
||||
Após a conclusão do treinamento, o CrewAI avalia as saídas dos agentes e consolida o feedback em sugestões acionáveis para cada agente. Essas sugestões são então aplicadas às execuções futuras do crew para melhorar a qualidade das saídas.
|
||||
|
||||
<Tip>
|
||||
Para detalhes sobre como o treinamento do CrewAI funciona internamente, consulte a página [Conceitos de Treinamento](/pt-BR/concepts/training).
|
||||
</Tip>
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Implantação ativa" icon="rocket">
|
||||
Você precisa de uma conta CrewAI AMP com uma implantação ativa em status **Ready** (tipo Crew).
|
||||
</Card>
|
||||
<Card title="Permissão de execução" icon="key">
|
||||
Sua conta deve ter permissão de execução para a implantação que deseja treinar.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Como treinar um crew
|
||||
|
||||
<Steps>
|
||||
<Step title="Abra a aba Training">
|
||||
Navegue até **Deployments**, clique na sua implantação e selecione a aba **Training**.
|
||||
</Step>
|
||||
|
||||
<Step title="Insira um nome de treinamento">
|
||||
Forneça um **Training Name** — este será o nome do arquivo `.pkl` usado para armazenar os resultados do treinamento. Por exemplo, "Expert Mode Training" produz `expert_mode_training.pkl`.
|
||||
</Step>
|
||||
|
||||
<Step title="Preencha as entradas do crew">
|
||||
Insira os campos de entrada do crew. Estas são as mesmas entradas que você forneceria para um kickoff normal — elas são carregadas dinamicamente com base na configuração do seu crew.
|
||||
</Step>
|
||||
|
||||
<Step title="Inicie o treinamento">
|
||||
Clique em **Train Crew**. O botão muda para "Training..." com um spinner enquanto o processo é executado.
|
||||
|
||||
Por trás dos panos:
|
||||
- Um registro de treinamento é criado para sua implantação
|
||||
- A plataforma chama o endpoint de auto-treinamento da implantação
|
||||
- O crew executa suas iterações automaticamente — nenhum feedback manual é necessário
|
||||
</Step>
|
||||
|
||||
<Step title="Monitore o progresso">
|
||||
O painel **Current Training Status** exibe:
|
||||
- **Status** — Estado atual da execução do treinamento
|
||||
- **Nº Iterations** — Número de iterações de treinamento configuradas
|
||||
- **Filename** — O arquivo `.pkl` sendo gerado
|
||||
- **Started At** — Quando o treinamento começou
|
||||
- **Training Inputs** — As entradas que você forneceu
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Entendendo os resultados do treinamento
|
||||
|
||||
Uma vez que o treinamento for concluído, você verá cards de resultado por agente com as seguintes informações:
|
||||
|
||||
- **Agent Role** — O nome/função do agente no seu crew
|
||||
- **Final Quality** — Uma pontuação de 0 a 10 avaliando a qualidade da saída do agente
|
||||
- **Final Summary** — Um resumo do desempenho do agente durante o treinamento
|
||||
- **Suggestions** — Recomendações acionáveis para melhorar o comportamento do agente
|
||||
|
||||
### Editando sugestões
|
||||
|
||||
Você pode refinar as sugestões para qualquer agente:
|
||||
|
||||
<Steps>
|
||||
<Step title="Clique em Edit">
|
||||
No card de resultado de qualquer agente, clique no botão **Edit** ao lado das sugestões.
|
||||
</Step>
|
||||
|
||||
<Step title="Modifique as sugestões">
|
||||
Atualize o texto das sugestões para refletir melhor as melhorias que você deseja.
|
||||
</Step>
|
||||
|
||||
<Step title="Salve as alterações">
|
||||
Clique em **Save**. As sugestões editadas são sincronizadas de volta à implantação e usadas em todas as execuções futuras.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Usando dados de treinamento
|
||||
|
||||
Para aplicar os resultados do treinamento ao seu crew:
|
||||
|
||||
1. Anote o **Training Filename** (o arquivo `.pkl`) da sua sessão de treinamento concluída.
|
||||
2. Especifique este nome de arquivo na configuração de kickoff ou execução da sua implantação.
|
||||
3. O crew carrega automaticamente o arquivo de treinamento e aplica as sugestões armazenadas a cada agente.
|
||||
|
||||
Isso significa que os agentes se beneficiam do feedback gerado durante o treinamento em cada execução subsequente.
|
||||
|
||||
## Treinamentos anteriores
|
||||
|
||||
A parte inferior da aba Training exibe um **histórico de todas as sessões de treinamento anteriores** da implantação. Use isso para revisar execuções de treinamento anteriores, comparar resultados ou selecionar um arquivo de treinamento diferente para usar.
|
||||
|
||||
## Tratamento de erros
|
||||
|
||||
Se uma execução de treinamento falhar, o painel de status mostra um estado de erro junto com uma mensagem descrevendo o que deu errado.
|
||||
|
||||
Causas comuns de falhas de treinamento:
|
||||
- **Runtime da implantação não atualizado** — Certifique-se de que sua implantação está executando a versão mais recente
|
||||
- **Erros de execução do crew** — Problemas na lógica de tarefas do crew ou configuração do agente
|
||||
- **Problemas de rede** — Problemas de conectividade entre a plataforma e a implantação
|
||||
|
||||
## Limitações
|
||||
|
||||
<Info>
|
||||
Tenha estas restrições em mente ao planejar seu fluxo de trabalho de treinamento:
|
||||
- **Um treinamento ativo por vez** por implantação — aguarde a execução atual terminar antes de iniciar outra
|
||||
- **Apenas modo de auto-treinamento** — a plataforma não suporta feedback interativo por iteração como o CLI
|
||||
- **Dados de treinamento são específicos da implantação** — os resultados do treinamento estão vinculados à instância e versão específicas da implantação
|
||||
</Info>
|
||||
|
||||
## Recursos relacionados
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Conceitos de Treinamento" icon="book" href="/pt-BR/concepts/training">
|
||||
Aprenda como o treinamento do CrewAI funciona internamente.
|
||||
</Card>
|
||||
<Card title="Kickoff Crew" icon="play" href="/pt-BR/enterprise/guides/kickoff-crew">
|
||||
Execute seu crew implantado a partir da plataforma AMP.
|
||||
</Card>
|
||||
<Card title="Implantar no AMP" icon="cloud-arrow-up" href="/pt-BR/enterprise/guides/deploy-to-amp">
|
||||
Faça a implantação do seu crew e deixe-o pronto para treinamento.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
93
docs/edge/pt-BR/enterprise/guides/update-crew.mdx
Normal file
93
docs/edge/pt-BR/enterprise/guides/update-crew.mdx
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: "Atualizar Crew"
|
||||
description: "Atualizando uma Crew no CrewAI AMP"
|
||||
icon: "pencil"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Após implantar sua crew no CrewAI AMP, 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 AMP
|
||||
2. Clique no botão `Re-deploy` na página de detalhes da sua crew
|
||||
|
||||
<Frame></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 AMP
|
||||
2. Encontre a seção `Bearer Token`
|
||||
3. Clique no botão `Reset` ao lado do token atual
|
||||
|
||||
<Frame></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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
126
docs/edge/pt-BR/enterprise/guides/webhook-automation.mdx
Normal file
126
docs/edge/pt-BR/enterprise/guides/webhook-automation.mdx
Normal file
@@ -0,0 +1,126 @@
|
||||
---
|
||||
title: "Automação com Webhook"
|
||||
description: "Automatize fluxos de trabalho do CrewAI AMP usando webhooks com plataformas como ActivePieces, Zapier e Make.com"
|
||||
icon: "webhook"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
O CrewAI AMP 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 AMP
|
||||
- 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 AMP
|
||||
- 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
|
||||
|
||||
**Nota:** Qualquer objeto `meta` fornecido na sua requisição de kickoff será incluído em todos os payloads de webhook, permitindo rastrear requisições e manter contexto durante todo o ciclo de vida da execução do crew.
|
||||
|
||||
<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>
|
||||
105
docs/edge/pt-BR/enterprise/guides/zapier-trigger.mdx
Normal file
105
docs/edge/pt-BR/enterprise/guides/zapier-trigger.mdx
Normal file
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: "Trigger Zapier"
|
||||
description: "Dispare crews do CrewAI a partir de fluxos de trabalho no Zapier para automatizar fluxos multiaplicativos"
|
||||
icon: "bolt"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
Este guia irá conduzi-lo pelo processo de configuração de triggers no Zapier para o CrewAI AMP, permitindo automatizar fluxos de trabalho entre CrewAI AMP e outros aplicativos.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
- Uma conta CrewAI AMP
|
||||
- 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 AMP">
|
||||
- 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 AMP">
|
||||
- Conecte sua conta CrewAI AMP.
|
||||
- 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 AMP">
|
||||
- Adicione outra etapa de ação para formatar a saída de texto do CrewAI AMP.
|
||||
- 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 AMP 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 AMP 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 AMP, permitindo fluxos de trabalho automatizados disparados por mensagens no Slack e resultando em notificações por e-mail com a saída do CrewAI AMP.
|
||||
265
docs/edge/pt-BR/enterprise/integrations/asana.mdx
Normal file
265
docs/edge/pt-BR/enterprise/integrations/asana.mdx
Normal file
@@ -0,0 +1,265 @@
|
||||
---
|
||||
title: Integração com Asana
|
||||
description: "Coordenação de tarefas e projetos em equipe com a integração Asana para CrewAI."
|
||||
icon: "circle"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP](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 AMP 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 de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
# 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.",
|
||||
apps=['asana']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
task_manager_agent = Agent(
|
||||
role="Task Manager",
|
||||
goal="Create and manage tasks efficiently",
|
||||
backstory="An AI assistant that focuses on task creation and management.",
|
||||
apps=['asana']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
project_coordinator = Agent(
|
||||
role="Project Coordinator",
|
||||
goal="Coordinate project activities and track progress",
|
||||
backstory="An experienced project coordinator who ensures projects run smoothly.",
|
||||
apps=['asana']
|
||||
)
|
||||
|
||||
# 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()
|
||||
```
|
||||
260
docs/edge/pt-BR/enterprise/integrations/box.mdx
Normal file
260
docs/edge/pt-BR/enterprise/integrations/box.mdx
Normal file
@@ -0,0 +1,260 @@
|
||||
---
|
||||
title: Integração com Box
|
||||
description: "Armazenamento de arquivos e gerenciamento de documentos com a integração do Box para CrewAI."
|
||||
icon: "box"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP](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 AMP](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 de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 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
|
||||
|
||||
# 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.",
|
||||
apps=['box']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['box']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['box']
|
||||
)
|
||||
|
||||
# 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()
|
||||
```
|
||||
300
docs/edge/pt-BR/enterprise/integrations/clickup.mdx
Normal file
300
docs/edge/pt-BR/enterprise/integrations/clickup.mdx
Normal file
@@ -0,0 +1,300 @@
|
||||
---
|
||||
title: Integração com ClickUp
|
||||
description: "Gerenciamento de tarefas e produtividade com integração ClickUp para CrewAI."
|
||||
icon: "list-check"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP](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 AMP 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 em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
# 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.",
|
||||
apps=['clickup']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
task_coordinator = Agent(
|
||||
role="Task Coordinator",
|
||||
goal="Create and manage tasks efficiently",
|
||||
backstory="An AI assistant that focuses on task creation and status management.",
|
||||
apps=['clickup']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['clickup']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['clickup']
|
||||
)
|
||||
|
||||
# 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>
|
||||
123
docs/edge/pt-BR/enterprise/integrations/databricks.mdx
Normal file
123
docs/edge/pt-BR/enterprise/integrations/databricks.mdx
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: Integração com Databricks
|
||||
description: "Conecte agentes CrewAI ao Databricks Genie, SQL, Unity Catalog Functions e Vector Search por meio dos servidores MCP gerenciados do Databricks."
|
||||
icon: "layer-group"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão geral
|
||||
|
||||
Conecte seus agentes CrewAI diretamente ao seu workspace do Databricks por meio dos [servidores MCP gerenciados do Databricks](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp). A integração com o Databricks permite que seus agentes façam perguntas em linguagem natural com o **Genie**, executem **SQL** governado, chamem **Unity Catalog Functions** e recuperem documentos com o **Vector Search** — tudo sem escrever ou hospedar qualquer código de conector, e com as permissões do Unity Catalog aplicadas em cada chamada.
|
||||
|
||||
Nos bastidores, a integração com o Databricks é um wrapper gerenciado sobre o suporte a [Servidores MCP personalizados](/pt-BR/enterprise/guides/custom-mcp-server) do CrewAI. O Databricks expõe cada recurso como seu próprio endpoint do [Model Context Protocol](https://modelcontextprotocol.io/), e o CrewAI se conecta a eles com segurança em seu nome. Como cada servidor é adicionado separadamente, você pode habilitar exatamente os recursos de que suas crews precisam.
|
||||
|
||||
## Principais recursos
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Genie" icon="comments">
|
||||
Faça perguntas em linguagem natural e obtenha respostas fundamentadas em seus dados com o [Genie](https://docs.databricks.com/aws/en/genie/), que consulta Genie Spaces e o Unity Catalog e fornece links de volta para a interface do Databricks.
|
||||
</Card>
|
||||
<Card title="Databricks SQL" icon="database">
|
||||
Execute SQL governado nos seus warehouses do Databricks para consultar, transformar e criar pipelines de dados diretamente a partir dos seus agentes.
|
||||
</Card>
|
||||
<Card title="Unity Catalog Functions" icon="function">
|
||||
Invoque [funções do Unity Catalog](https://docs.databricks.com/aws/en/udf/unity-catalog) para executar SQL predefinido e lógica de negócio personalizada como ferramentas governadas e reutilizáveis.
|
||||
</Card>
|
||||
<Card title="Vector Search" icon="magnifying-glass">
|
||||
Recupere documentos relevantes para fluxos de RAG e de conhecimento a partir de índices do [Mosaic AI Vector Search](https://docs.databricks.com/aws/en/generative-ai/vector-search) usando similaridade semântica.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Todos os servidores são executados por trás do Unity AI Gateway e aplicam os controles de acesso do Unity Catalog, de modo que seus agentes só enxergam os dados e as ferramentas que têm permissão para usar.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
Antes de usar a integração com o Databricks, certifique-se de ter:
|
||||
|
||||
- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa
|
||||
- Um workspace do Databricks com os recursos que você deseja expor (Genie Spaces, warehouses SQL, funções do Unity Catalog ou índices do Vector Search)
|
||||
- [Privilégios apropriados do Unity Catalog](https://docs.databricks.com/aws/en/data-governance/unity-catalog) nos objetos subjacentes
|
||||
- O hostname do seu workspace do Databricks (ex.: `your-workspace.cloud.databricks.com`)
|
||||
|
||||
## Servidores MCP gerenciados do Databricks
|
||||
|
||||
O Databricks publica um servidor MCP gerenciado separado para cada recurso. O CrewAI os expõe como conexões individuais, cada uma configurada com o host do seu workspace e os identificadores relevantes do Unity Catalog. Os endpoints seguem estes padrões:
|
||||
|
||||
| Servidor | O que faz | Padrão de URL MCP |
|
||||
|----------|-----------|-------------------|
|
||||
| **Genie** | Perguntas e respostas em linguagem natural sobre um Genie Space | `https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}` |
|
||||
| **Databricks SQL** | Executa SQL nos seus warehouses | `https://<workspace-hostname>/api/2.0/mcp/sql` |
|
||||
| **Unity Catalog Functions** | Executa funções UC registradas | `https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}` |
|
||||
| **Vector Search** | Consulta um índice do Vector Search | `https://<workspace-hostname>/api/2.0/mcp/vector-search/{catalog}/{schema}` |
|
||||
|
||||
<Note>
|
||||
Você não precisa construir essas URLs manualmente — o CrewAI cria cada endpoint a partir do host do workspace e dos identificadores (Genie Space ID, ou catalog/schema) que você fornece ao configurar a conexão. Para a especificação completa e os detalhes mais recentes dos endpoints, consulte a [documentação de MCP gerenciado do Databricks](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp).
|
||||
</Note>
|
||||
|
||||
## Conectando o Databricks no CrewAI AMP
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/databricks-configure.png" alt="Configurar um servidor MCP gerenciado do Databricks no CrewAI AMP" />
|
||||
</Frame>
|
||||
|
||||
Cada recurso do Databricks — **Databricks Genie**, **Databricks SQL**, **Databricks Unity Catalog Functions** e **Databricks Vector Search** — aparece como seu próprio servidor MCP no grupo Databricks da página **Tools & Integrations**. Configure os que você precisar:
|
||||
|
||||
<Steps>
|
||||
<Step title="Abra Tools & Integrations">
|
||||
Navegue até **Tools & Integrations** na barra lateral esquerda do CrewAI AMP e localize o grupo **Databricks** na lista de Connections. Você verá os servidores Genie, SQL, Unity Catalog Functions e Vector Search listados abaixo dele.
|
||||
</Step>
|
||||
|
||||
<Step title="Configure um servidor">
|
||||
Clique em **Configure** ao lado do recurso que deseja habilitar e forneça os detalhes da conexão:
|
||||
|
||||
- **Workspace Host** — o hostname do seu workspace do Databricks (ex.: `my-workspace.cloud.databricks.com`).
|
||||
- **Genie** — o **Genie Space ID** a ser consultado.
|
||||
- **Unity Catalog Functions** — o **catalog** e o **schema** que contêm suas funções.
|
||||
- **Vector Search** — o **catalog** e o **schema** que contêm seu índice.
|
||||
- **Databricks SQL** — sem identificadores adicionais; as consultas são executadas nos warehouses SQL do seu workspace.
|
||||
</Step>
|
||||
|
||||
<Step title="Escolha um método de autenticação">
|
||||
Selecione como o CrewAI se autentica no Databricks. **OAuth** é recomendado.
|
||||
|
||||
- **Use OAuth** — Conecte-se com segurança usando OAuth 2.0. Cada usuário se autentica individualmente, e o Databricks emite tokens com escopo para o recurso (`genie`, `sql`, `unity-catalog` ou `vector-search`). O CrewAI gerencia o fluxo de autorização e renova os tokens automaticamente.
|
||||
- **Use personal access token** — Autentique-se com um [token de acesso pessoal do Databricks](https://docs.databricks.com/aws/en/dev-tools/auth/pat). Use uma identidade com privilégios mínimos para limitar a exposição.
|
||||
</Step>
|
||||
|
||||
<Step title="Autentique">
|
||||
Conclua a autenticação. Uma vez conectado, as ferramentas do servidor ficam disponíveis para suas crews. Repita para qualquer outro recurso do Databricks que você queira habilitar.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
Como cada recurso é uma conexão separada, você pode combiná-los livremente — por exemplo, habilitar Genie e Vector Search para uma crew de pesquisa e reservar SQL e Unity Catalog Functions para uma crew de engenharia de dados. As configurações de visibilidade permitem controlar quais membros da equipe podem usar cada um.
|
||||
</Tip>
|
||||
|
||||
## Usando as ferramentas do Databricks nas suas crews
|
||||
|
||||
Uma vez conectado, as ferramentas que cada servidor MCP expõe aparecem junto às conexões integradas na página **Tools & Integrations**. Você pode:
|
||||
|
||||
- **Atribuir ferramentas aos agentes** nas suas crews, como qualquer outra ferramenta do CrewAI.
|
||||
- **Gerenciar a visibilidade** para controlar quais membros da equipe podem usar cada conexão.
|
||||
- **Editar ou remover** qualquer conexão a qualquer momento na lista de Connections.
|
||||
|
||||
Seus agentes agora podem pedir respostas fundamentadas ao Genie, executar SQL nos seus warehouses, chamar funções do Unity Catalog e pesquisar índices do Vector Search — com os resultados retornando automaticamente ao raciocínio deles.
|
||||
|
||||
<Warning>
|
||||
O Databricks aplica governança por meio do Unity Catalog e do Unity AI Gateway: um usuário só pode descobrir e invocar ferramentas que a identidade do seu workspace tem permissão para usar. Se uma chamada de ferramenta falhar, confirme se o usuário (ou a identidade do token) que está conectando tem os privilégios necessários do Unity Catalog no Genie Space, warehouse, função ou índice. Algumas consultas do Genie e do SQL são executadas de forma assíncrona e podem levar um momento para retornar resultados.
|
||||
</Warning>
|
||||
|
||||
## Saiba mais
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Servidores MCP gerenciados do Databricks" icon="layer-group" href="https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp">
|
||||
Documentação oficial do Databricks para os servidores MCP gerenciados Genie, SQL, Unity Catalog Functions e Vector Search.
|
||||
</Card>
|
||||
<Card title="Servidores MCP personalizados no CrewAI" icon="plug" href="/pt-BR/enterprise/guides/custom-mcp-server">
|
||||
Saiba como o CrewAI se conecta a qualquer servidor MCP, a base sobre a qual a integração com o Databricks é construída.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Card title="Precisa de ajuda?" icon="headset" href="mailto:support@crewai.com">
|
||||
Entre em contato com nossa equipe de suporte para obter ajuda com a configuração da integração com o Databricks ou com a solução de problemas.
|
||||
</Card>
|
||||
312
docs/edge/pt-BR/enterprise/integrations/github.mdx
Normal file
312
docs/edge/pt-BR/enterprise/integrations/github.mdx
Normal file
@@ -0,0 +1,312 @@
|
||||
---
|
||||
title: Integração com GitHub
|
||||
description: "Gerenciamento de repositórios e issues com a integração do GitHub para CrewAI."
|
||||
icon: "github"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP](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 AMP](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 em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 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
|
||||
|
||||
# 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.",
|
||||
apps=['github']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
issue_manager = Agent(
|
||||
role="Issue Manager",
|
||||
goal="Create and manage GitHub issues efficiently",
|
||||
backstory="An AI assistant that focuses on issue tracking and management.",
|
||||
apps=['github']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
release_manager = Agent(
|
||||
role="Release Manager",
|
||||
goal="Manage software releases and versioning",
|
||||
backstory="An experienced release manager who handles version control and release processes.",
|
||||
apps=['github']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['github']
|
||||
)
|
||||
|
||||
# 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/edge/pt-BR/enterprise/integrations/gmail.mdx
Normal file
356
docs/edge/pt-BR/enterprise/integrations/gmail.mdx
Normal 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"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP](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 AMP](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 Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## 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/fetch_emails">
|
||||
**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
|
||||
|
||||
# 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.",
|
||||
apps=['gmail']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['gmail']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
contact_manager = Agent(
|
||||
role="Contact Manager",
|
||||
goal="Manage and organize email contacts efficiently",
|
||||
backstory="An experienced contact manager who maintains organized contact databases.",
|
||||
apps=['gmail']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['gmail']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
workflow_manager = Agent(
|
||||
role="Email Workflow Manager",
|
||||
goal="Automate email workflows and responses",
|
||||
backstory="An AI assistant that manages automated email workflows and responses.",
|
||||
apps=['gmail']
|
||||
)
|
||||
|
||||
# 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>
|
||||
405
docs/edge/pt-BR/enterprise/integrations/google_calendar.mdx
Normal file
405
docs/edge/pt-BR/enterprise/integrations/google_calendar.mdx
Normal file
@@ -0,0 +1,405 @@
|
||||
---
|
||||
title: Integração com Google Calendar
|
||||
description: "Gerenciamento de eventos e agendas com integração ao Google Calendar para o CrewAI."
|
||||
icon: "calendar"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP](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 AMP](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 em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## 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/view_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
|
||||
|
||||
# Obter ferramentas empresariais (as ferramentas do Google Calendar serão incluídas)
|
||||
|
||||
# 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.",
|
||||
apps=['google_calendar']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
# Obter apenas ferramentas específicas do Google Calendar
|
||||
actions_list=["google_calendar/create_event", "google_calendar/view_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.",
|
||||
apps=['google_calendar']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['google_calendar']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['google_calendar']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['google_calendar']
|
||||
)
|
||||
|
||||
# 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>
|
||||
341
docs/edge/pt-BR/enterprise/integrations/google_contacts.mdx
Normal file
341
docs/edge/pt-BR/enterprise/integrations/google_contacts.mdx
Normal file
@@ -0,0 +1,341 @@
|
||||
---
|
||||
title: Integração Google Contacts
|
||||
description: "Gerenciamento de contatos e diretório com integração Google Contacts para CrewAI."
|
||||
icon: "address-book"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Permita que seus agentes gerenciem informações de contatos e diretório através do Google Contacts. Acesse contatos pessoais, pesquise pessoas no diretório, crie e atualize informações de contato, e gerencie grupos de contatos com automação alimentada por IA.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
Antes de usar a integração Google Contacts, certifique-se de ter:
|
||||
|
||||
- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa
|
||||
- Uma conta Google com acesso ao Google Contacts
|
||||
- Conectado sua conta Google através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
|
||||
|
||||
## Configurando a Integração Google Contacts
|
||||
|
||||
### 1. Conecte sua Conta Google
|
||||
|
||||
1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors)
|
||||
2. Encontre **Google Contacts** 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 a contatos e diretório
|
||||
5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## Ações Disponíveis
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="google_contacts/get_contacts">
|
||||
**Descrição:** Recuperar contatos do usuário do Google Contacts.
|
||||
|
||||
**Parâmetros:**
|
||||
- `pageSize` (integer, opcional): Número de contatos a retornar (máx 1000). Mínimo: 1, Máximo: 1000
|
||||
- `pageToken` (string, opcional): O token da página a recuperar.
|
||||
- `personFields` (string, opcional): Campos a incluir (ex: 'names,emailAddresses,phoneNumbers'). Padrão: names,emailAddresses,phoneNumbers
|
||||
- `requestSyncToken` (boolean, opcional): Se a resposta deve incluir um token de sincronização. Padrão: false
|
||||
- `sortOrder` (string, opcional): A ordem na qual as conexões devem ser classificadas. Opções: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, LAST_NAME_ASCENDING
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/search_contacts">
|
||||
**Descrição:** Pesquisar por contatos usando uma string de consulta.
|
||||
|
||||
**Parâmetros:**
|
||||
- `query` (string, obrigatório): String de consulta de pesquisa
|
||||
- `readMask` (string, obrigatório): Campos a ler (ex: 'names,emailAddresses,phoneNumbers')
|
||||
- `pageSize` (integer, opcional): Número de resultados a retornar. Mínimo: 1, Máximo: 30
|
||||
- `pageToken` (string, opcional): Token especificando qual página de resultado retornar.
|
||||
- `sources` (array, opcional): As fontes para pesquisar. Opções: READ_SOURCE_TYPE_CONTACT, READ_SOURCE_TYPE_PROFILE. Padrão: READ_SOURCE_TYPE_CONTACT
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/list_directory_people">
|
||||
**Descrição:** Listar pessoas no diretório do usuário autenticado.
|
||||
|
||||
**Parâmetros:**
|
||||
- `sources` (array, obrigatório): Fontes de diretório para pesquisar. Opções: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE, DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT. Padrão: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE
|
||||
- `pageSize` (integer, opcional): Número de pessoas a retornar. Mínimo: 1, Máximo: 1000
|
||||
- `pageToken` (string, opcional): Token especificando qual página de resultado retornar.
|
||||
- `readMask` (string, opcional): Campos a ler (ex: 'names,emailAddresses')
|
||||
- `requestSyncToken` (boolean, opcional): Se a resposta deve incluir um token de sincronização. Padrão: false
|
||||
- `mergeSources` (array, opcional): Dados adicionais para mesclar nas respostas de pessoas do diretório. Opções: CONTACT
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/search_directory_people">
|
||||
**Descrição:** Pesquisar por pessoas no diretório.
|
||||
|
||||
**Parâmetros:**
|
||||
- `query` (string, obrigatório): Consulta de pesquisa
|
||||
- `sources` (string, obrigatório): Fontes de diretório (use 'DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE')
|
||||
- `pageSize` (integer, opcional): Número de resultados a retornar
|
||||
- `readMask` (string, opcional): Campos a ler
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/list_other_contacts">
|
||||
**Descrição:** Listar outros contatos (não nos contatos pessoais do usuário).
|
||||
|
||||
**Parâmetros:**
|
||||
- `pageSize` (integer, opcional): Número de contatos a retornar. Mínimo: 1, Máximo: 1000
|
||||
- `pageToken` (string, opcional): Token especificando qual página de resultado retornar.
|
||||
- `readMask` (string, opcional): Campos a ler
|
||||
- `requestSyncToken` (boolean, opcional): Se a resposta deve incluir um token de sincronização. Padrão: false
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/search_other_contacts">
|
||||
**Descrição:** Pesquisar outros contatos.
|
||||
|
||||
**Parâmetros:**
|
||||
- `query` (string, obrigatório): Consulta de pesquisa
|
||||
- `readMask` (string, obrigatório): Campos a ler (ex: 'names,emailAddresses')
|
||||
- `pageSize` (integer, opcional): Número de resultados
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/get_person">
|
||||
**Descrição:** Obter informações de contato de uma única pessoa por nome do recurso.
|
||||
|
||||
**Parâmetros:**
|
||||
- `resourceName` (string, obrigatório): O nome do recurso da pessoa a obter (ex: 'people/c123456789')
|
||||
- `personFields` (string, opcional): Campos a incluir (ex: 'names,emailAddresses,phoneNumbers'). Padrão: names,emailAddresses,phoneNumbers
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/create_contact">
|
||||
**Descrição:** Criar um novo contato no catálogo de endereços do usuário.
|
||||
|
||||
**Parâmetros:**
|
||||
- `names` (array, opcional): Nomes da pessoa. Cada item é um objeto com `givenName` (string), `familyName` (string), `displayName` (string).
|
||||
- `emailAddresses` (array, opcional): Endereços de email. Cada item é um objeto com `value` (string, endereço de email) e `type` (string, 'home', 'work', 'other', padrão 'other').
|
||||
- `phoneNumbers` (array, opcional): Números de telefone. Cada item é um objeto com `value` (string, número de telefone) e `type` (string, 'home', 'work', 'mobile', 'other', padrão 'other').
|
||||
- `addresses` (array, opcional): Endereços postais. Cada item é um objeto com `formattedValue` (string, endereço formatado) e `type` (string, 'home', 'work', 'other', padrão 'other').
|
||||
- `organizations` (array, opcional): Organizações/empresas. Cada item é um objeto com `name` (string, nome da organização), `title` (string, cargo) e `type` (string, 'work', 'other', padrão 'work').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/update_contact">
|
||||
**Descrição:** Atualizar informações de um contato existente.
|
||||
|
||||
**Parâmetros:**
|
||||
- `resourceName` (string, obrigatório): O nome do recurso da pessoa a atualizar (ex: 'people/c123456789').
|
||||
- `updatePersonFields` (string, obrigatório): Campos a atualizar (ex: 'names,emailAddresses,phoneNumbers').
|
||||
- `names` (array, opcional): Nomes da pessoa. Cada item é um objeto com `givenName` (string), `familyName` (string), `displayName` (string).
|
||||
- `emailAddresses` (array, opcional): Endereços de email. Cada item é um objeto com `value` (string, endereço de email) e `type` (string, 'home', 'work', 'other').
|
||||
- `phoneNumbers` (array, opcional): Números de telefone. Cada item é um objeto com `value` (string, número de telefone) e `type` (string, 'home', 'work', 'mobile', 'other').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/delete_contact">
|
||||
**Descrição:** Excluir um contato do catálogo de endereços do usuário.
|
||||
|
||||
**Parâmetros:**
|
||||
- `resourceName` (string, obrigatório): O nome do recurso da pessoa a excluir (ex: 'people/c123456789').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/batch_get_people">
|
||||
**Descrição:** Obter informações sobre várias pessoas em uma única solicitação.
|
||||
|
||||
**Parâmetros:**
|
||||
- `resourceNames` (array, obrigatório): Nomes de recursos das pessoas a obter (máx 200 itens).
|
||||
- `personFields` (string, opcional): Campos a incluir (ex: 'names,emailAddresses,phoneNumbers'). Padrão: names,emailAddresses,phoneNumbers
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/list_contact_groups">
|
||||
**Descrição:** Listar os grupos de contatos (rótulos) do usuário.
|
||||
|
||||
**Parâmetros:**
|
||||
- `pageSize` (integer, opcional): Número de grupos de contatos a retornar. Mínimo: 1, Máximo: 1000
|
||||
- `pageToken` (string, opcional): Token especificando qual página de resultado retornar.
|
||||
- `groupFields` (string, opcional): Campos a incluir (ex: 'name,memberCount,clientData'). Padrão: name,memberCount
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/get_contact_group">
|
||||
**Descrição:** Obter um grupo de contatos específico por nome do recurso.
|
||||
|
||||
**Parâmetros:**
|
||||
- `resourceName` (string, obrigatório): O nome do recurso do grupo de contatos (ex: 'contactGroups/myContactGroup').
|
||||
- `maxMembers` (integer, opcional): Número máximo de membros a incluir. Mínimo: 0, Máximo: 20000
|
||||
- `groupFields` (string, opcional): Campos a incluir (ex: 'name,memberCount,clientData'). Padrão: name,memberCount
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/create_contact_group">
|
||||
**Descrição:** Criar um novo grupo de contatos (rótulo).
|
||||
|
||||
**Parâmetros:**
|
||||
- `name` (string, obrigatório): O nome do grupo de contatos.
|
||||
- `clientData` (array, opcional): Dados específicos do cliente. Cada item é um objeto com `key` (string) e `value` (string).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/update_contact_group">
|
||||
**Descrição:** Atualizar informações de um grupo de contatos.
|
||||
|
||||
**Parâmetros:**
|
||||
- `resourceName` (string, obrigatório): O nome do recurso do grupo de contatos (ex: 'contactGroups/myContactGroup').
|
||||
- `name` (string, obrigatório): O nome do grupo de contatos.
|
||||
- `clientData` (array, opcional): Dados específicos do cliente. Cada item é um objeto com `key` (string) e `value` (string).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/delete_contact_group">
|
||||
**Descrição:** Excluir um grupo de contatos.
|
||||
|
||||
**Parâmetros:**
|
||||
- `resourceName` (string, obrigatório): O nome do recurso do grupo de contatos a excluir (ex: 'contactGroups/myContactGroup').
|
||||
- `deleteContacts` (boolean, opcional): Se os contatos do grupo também devem ser excluídos. Padrão: false
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Exemplos de Uso
|
||||
|
||||
### Configuração Básica do Agente Google Contacts
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente com capacidades do Google Contacts
|
||||
contacts_agent = Agent(
|
||||
role="Gerenciador de Contatos",
|
||||
goal="Gerenciar Google Contacts de forma eficiente",
|
||||
backstory="Um assistente IA especializado em gerenciamento e organização de contatos.",
|
||||
apps=['google_contacts'] # Todas as ações do Google Contacts estarão disponíveis
|
||||
)
|
||||
|
||||
# Tarefa para criar um novo contato
|
||||
create_contact_task = Task(
|
||||
description="Criar um novo contato chamado 'João Silva' com email 'joao.silva@exemplo.com' e telefone '11-98765-4321'",
|
||||
agent=contacts_agent,
|
||||
expected_output="Novo contato criado com sucesso"
|
||||
)
|
||||
|
||||
# Execute a tarefa
|
||||
crew = Crew(
|
||||
agents=[contacts_agent],
|
||||
tasks=[create_contact_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### Pesquisando e Listando Contatos
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente focado em pesquisar contatos
|
||||
search_agent = Agent(
|
||||
role="Pesquisador de Contatos",
|
||||
goal="Encontrar e recuperar informações de contato",
|
||||
backstory="Um assistente IA habilidoso em pesquisar e listar contatos.",
|
||||
apps=['google_contacts/search_contacts', 'google_contacts/get_contacts']
|
||||
)
|
||||
|
||||
# Tarefa para pesquisar contatos
|
||||
search_task = Task(
|
||||
description="Pesquisar por contatos chamados 'Maria' e listar seus endereços de email e números de telefone.",
|
||||
agent=search_agent,
|
||||
expected_output="Lista de contatos correspondentes a 'Maria' com seus detalhes de email e telefone."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[search_agent],
|
||||
tasks=[search_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### Gerenciando Grupos de Contatos
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente para gerenciar grupos de contatos
|
||||
group_manager = Agent(
|
||||
role="Organizador de Grupos de Contatos",
|
||||
goal="Organizar contatos em grupos e gerenciar membros dos grupos",
|
||||
backstory="Um assistente IA especializado em criar e gerenciar grupos do Google Contacts.",
|
||||
apps=['google_contacts/create_contact_group', 'google_contacts/list_contact_groups']
|
||||
)
|
||||
|
||||
# Tarefa para criar um novo grupo de contatos
|
||||
create_group_task = Task(
|
||||
description="Criar um novo grupo de contatos chamado 'Equipe de Marketing' e listar todos os grupos existentes.",
|
||||
agent=group_manager,
|
||||
expected_output="Novo grupo de contatos 'Equipe de Marketing' criado e lista de todos os grupos retornada."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[group_manager],
|
||||
tasks=[create_group_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Problemas Comuns
|
||||
|
||||
**Erros de Autenticação**
|
||||
|
||||
- Certifique-se de que sua conta Google tenha as permissões necessárias para acesso a contatos e diretório.
|
||||
- Verifique se a conexão OAuth inclui todos os escopos necessários para a API Google People.
|
||||
|
||||
**Problemas de Criação/Atualização de Contatos**
|
||||
|
||||
- Certifique-se de que campos obrigatórios como `email` sejam fornecidos para criação de contatos.
|
||||
- Verifique se o `resourceName` está correto ao atualizar ou excluir contatos.
|
||||
- Confirme se o formato dos dados para `names`, `emailAddresses`, `phoneNumbers`, etc., corresponde às especificações da API.
|
||||
|
||||
**Problemas de Pesquisa e Filtro**
|
||||
|
||||
- Certifique-se de que os parâmetros de `query` e `readMask` estejam especificados corretamente para `search_contacts` e `search_other_contacts`.
|
||||
- Para pesquisas de diretório, certifique-se de que `sources` esteja definido corretamente (ex: 'DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE').
|
||||
|
||||
**Gerenciamento de Grupos de Contatos**
|
||||
|
||||
- Ao criar um grupo de contatos, certifique-se de que o `name` seja fornecido.
|
||||
- Para `get_contact_group`, certifique-se de que o `resourceName` esteja correto.
|
||||
|
||||
### 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 com configuração
|
||||
ou solução de problemas da integração Google Contacts.
|
||||
</Card>
|
||||
550
docs/edge/pt-BR/enterprise/integrations/google_docs.mdx
Normal file
550
docs/edge/pt-BR/enterprise/integrations/google_docs.mdx
Normal file
@@ -0,0 +1,550 @@
|
||||
---
|
||||
title: Integração Google Docs
|
||||
description: "Criação e edição de documentos com integração Google Docs para CrewAI."
|
||||
icon: "file-lines"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Permita que seus agentes criem, editem e gerenciem documentos do Google Docs com manipulação de texto e formatação. Automatize a criação de documentos, insira e substitua texto, gerencie intervalos de conteúdo e simplifique seus fluxos de trabalho de documentos com automação alimentada por IA.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
Antes de usar a integração Google Docs, certifique-se de ter:
|
||||
|
||||
- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa
|
||||
- Uma conta Google com acesso ao Google Docs
|
||||
- Conectado sua conta Google através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
|
||||
|
||||
## Configurando a Integração Google Docs
|
||||
|
||||
### 1. Conecte sua Conta Google
|
||||
|
||||
1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors)
|
||||
2. Encontre **Google Docs** 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 a documentos
|
||||
5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## Ações Disponíveis
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="google_docs/create_document">
|
||||
**Descrição:** Criar um novo documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `title` (string, opcional): O título para o novo documento.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/get_document">
|
||||
**Descrição:** Obter o conteúdo e metadados de um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento a recuperar.
|
||||
- `includeTabsContent` (boolean, opcional): Se deve incluir conteúdo de abas. Padrão: false
|
||||
- `suggestionsViewMode` (string, opcional): O modo de visualização de sugestões a aplicar ao documento. Opções: DEFAULT_FOR_CURRENT_ACCESS, PREVIEW_SUGGESTIONS_ACCEPTED, PREVIEW_WITHOUT_SUGGESTIONS. Padrão: DEFAULT_FOR_CURRENT_ACCESS
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/batch_update">
|
||||
**Descrição:** Aplicar uma ou mais atualizações a um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento a atualizar.
|
||||
- `requests` (array, obrigatório): Uma lista de atualizações a aplicar ao documento. Cada item é um objeto representando uma solicitação.
|
||||
- `writeControl` (object, opcional): Fornece controle sobre como as solicitações de escrita são executadas. Contém `requiredRevisionId` (string) e `targetRevisionId` (string).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_text">
|
||||
**Descrição:** Inserir texto em um documento do Google em um local específico.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento a atualizar.
|
||||
- `text` (string, obrigatório): O texto a inserir.
|
||||
- `index` (integer, opcional): O índice baseado em zero onde inserir o texto. Padrão: 1
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/replace_text">
|
||||
**Descrição:** Substituir todas as instâncias de texto em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento a atualizar.
|
||||
- `containsText` (string, obrigatório): O texto a encontrar e substituir.
|
||||
- `replaceText` (string, obrigatório): O texto para substituir.
|
||||
- `matchCase` (boolean, opcional): Se a pesquisa deve respeitar maiúsculas e minúsculas. Padrão: false
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/delete_content_range">
|
||||
**Descrição:** Excluir conteúdo de um intervalo específico em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento a atualizar.
|
||||
- `startIndex` (integer, obrigatório): O índice inicial do intervalo a excluir.
|
||||
- `endIndex` (integer, obrigatório): O índice final do intervalo a excluir.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_page_break">
|
||||
**Descrição:** Inserir uma quebra de página em um local específico em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento a atualizar.
|
||||
- `index` (integer, opcional): O índice baseado em zero onde inserir a quebra de página. Padrão: 1
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/create_named_range">
|
||||
**Descrição:** Criar um intervalo nomeado em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento a atualizar.
|
||||
- `name` (string, obrigatório): O nome para o intervalo nomeado.
|
||||
- `startIndex` (integer, obrigatório): O índice inicial do intervalo.
|
||||
- `endIndex` (integer, obrigatório): O índice final do intervalo.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/create_document_with_content">
|
||||
**Descrição:** Criar um novo documento do Google com conteúdo em uma única ação.
|
||||
|
||||
**Parâmetros:**
|
||||
- `title` (string, obrigatório): O título para o novo documento. Aparece no topo do documento e no Google Drive.
|
||||
- `content` (string, opcional): O conteúdo de texto a inserir no documento. Use `\n` para novos parágrafos.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/append_text">
|
||||
**Descrição:** Adicionar texto ao final de um documento do Google. Insere automaticamente no final do documento sem necessidade de especificar um índice.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento obtido da resposta de create_document ou URL.
|
||||
- `text` (string, obrigatório): Texto a adicionar ao final do documento. Use `\n` para novos parágrafos.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_text_bold">
|
||||
**Descrição:** Aplicar ou remover formatação de negrito em texto de um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `startIndex` (integer, obrigatório): Posição inicial do texto a formatar.
|
||||
- `endIndex` (integer, obrigatório): Posição final do texto a formatar (exclusivo).
|
||||
- `bold` (boolean, obrigatório): Defina `true` para aplicar negrito, `false` para remover negrito.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_text_italic">
|
||||
**Descrição:** Aplicar ou remover formatação de itálico em texto de um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `startIndex` (integer, obrigatório): Posição inicial do texto a formatar.
|
||||
- `endIndex` (integer, obrigatório): Posição final do texto a formatar (exclusivo).
|
||||
- `italic` (boolean, obrigatório): Defina `true` para aplicar itálico, `false` para remover itálico.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_text_underline">
|
||||
**Descrição:** Adicionar ou remover formatação de sublinhado em texto de um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `startIndex` (integer, obrigatório): Posição inicial do texto a formatar.
|
||||
- `endIndex` (integer, obrigatório): Posição final do texto a formatar (exclusivo).
|
||||
- `underline` (boolean, obrigatório): Defina `true` para sublinhar, `false` para remover sublinhado.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_text_strikethrough">
|
||||
**Descrição:** Adicionar ou remover formatação de tachado em texto de um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `startIndex` (integer, obrigatório): Posição inicial do texto a formatar.
|
||||
- `endIndex` (integer, obrigatório): Posição final do texto a formatar (exclusivo).
|
||||
- `strikethrough` (boolean, obrigatório): Defina `true` para adicionar tachado, `false` para remover.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_font_size">
|
||||
**Descrição:** Alterar o tamanho da fonte do texto em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `startIndex` (integer, obrigatório): Posição inicial do texto a formatar.
|
||||
- `endIndex` (integer, obrigatório): Posição final do texto a formatar (exclusivo).
|
||||
- `fontSize` (number, obrigatório): Tamanho da fonte em pontos. Tamanhos comuns: 10, 11, 12, 14, 16, 18, 24, 36.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_text_color">
|
||||
**Descrição:** Alterar a cor do texto usando valores RGB (escala 0-1) em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `startIndex` (integer, obrigatório): Posição inicial do texto a formatar.
|
||||
- `endIndex` (integer, obrigatório): Posição final do texto a formatar (exclusivo).
|
||||
- `red` (number, obrigatório): Componente vermelho (0-1). Exemplo: `1` para vermelho total.
|
||||
- `green` (number, obrigatório): Componente verde (0-1). Exemplo: `0.5` para metade verde.
|
||||
- `blue` (number, obrigatório): Componente azul (0-1). Exemplo: `0` para sem azul.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/create_hyperlink">
|
||||
**Descrição:** Transformar texto existente em um hyperlink clicável em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `startIndex` (integer, obrigatório): Posição inicial do texto a transformar em link.
|
||||
- `endIndex` (integer, obrigatório): Posição final do texto a transformar em link (exclusivo).
|
||||
- `url` (string, obrigatório): A URL para a qual o link deve apontar. Exemplo: `"https://example.com"`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/apply_heading_style">
|
||||
**Descrição:** Aplicar um estilo de título ou parágrafo a um intervalo de texto em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `startIndex` (integer, obrigatório): Posição inicial do(s) parágrafo(s) a estilizar.
|
||||
- `endIndex` (integer, obrigatório): Posição final do(s) parágrafo(s) a estilizar.
|
||||
- `style` (string, obrigatório): O estilo a aplicar. Opções: `NORMAL_TEXT`, `TITLE`, `SUBTITLE`, `HEADING_1`, `HEADING_2`, `HEADING_3`, `HEADING_4`, `HEADING_5`, `HEADING_6`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_paragraph_alignment">
|
||||
**Descrição:** Definir o alinhamento de texto para parágrafos em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `startIndex` (integer, obrigatório): Posição inicial do(s) parágrafo(s) a alinhar.
|
||||
- `endIndex` (integer, obrigatório): Posição final do(s) parágrafo(s) a alinhar.
|
||||
- `alignment` (string, obrigatório): Alinhamento do texto. Opções: `START` (esquerda), `CENTER`, `END` (direita), `JUSTIFIED`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_line_spacing">
|
||||
**Descrição:** Definir o espaçamento entre linhas para parágrafos em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `startIndex` (integer, obrigatório): Posição inicial do(s) parágrafo(s).
|
||||
- `endIndex` (integer, obrigatório): Posição final do(s) parágrafo(s).
|
||||
- `lineSpacing` (number, obrigatório): Espaçamento entre linhas como porcentagem. `100` = simples, `115` = 1.15x, `150` = 1.5x, `200` = duplo.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/create_paragraph_bullets">
|
||||
**Descrição:** Converter parágrafos em uma lista com marcadores ou numerada em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `startIndex` (integer, obrigatório): Posição inicial dos parágrafos a converter em lista.
|
||||
- `endIndex` (integer, obrigatório): Posição final dos parágrafos a converter em lista.
|
||||
- `bulletPreset` (string, obrigatório): Estilo de marcadores/numeração. Opções: `BULLET_DISC_CIRCLE_SQUARE`, `BULLET_DIAMONDX_ARROW3D_SQUARE`, `BULLET_CHECKBOX`, `BULLET_ARROW_DIAMOND_DISC`, `BULLET_STAR_CIRCLE_SQUARE`, `NUMBERED_DECIMAL_ALPHA_ROMAN`, `NUMBERED_DECIMAL_ALPHA_ROMAN_PARENS`, `NUMBERED_DECIMAL_NESTED`, `NUMBERED_UPPERALPHA_ALPHA_ROMAN`, `NUMBERED_UPPERROMAN_UPPERALPHA_DECIMAL`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/delete_paragraph_bullets">
|
||||
**Descrição:** Remover marcadores ou numeração de parágrafos em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `startIndex` (integer, obrigatório): Posição inicial dos parágrafos de lista.
|
||||
- `endIndex` (integer, obrigatório): Posição final dos parágrafos de lista.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_table_with_content">
|
||||
**Descrição:** Inserir uma tabela com conteúdo em um documento do Google em uma única ação. Forneça o conteúdo como um array 2D.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `rows` (integer, obrigatório): Número de linhas na tabela.
|
||||
- `columns` (integer, obrigatório): Número de colunas na tabela.
|
||||
- `index` (integer, opcional): Posição para inserir a tabela. Se não fornecido, a tabela é inserida no final do documento.
|
||||
- `content` (array, obrigatório): Conteúdo da tabela como um array 2D. Cada array interno é uma linha. Exemplo: `[["Ano", "Receita"], ["2023", "$43B"], ["2024", "$45B"]]`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_table_row">
|
||||
**Descrição:** Inserir uma nova linha acima ou abaixo de uma célula de referência em uma tabela existente.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `tableStartIndex` (integer, obrigatório): O índice inicial da tabela. Obtenha de get_document.
|
||||
- `rowIndex` (integer, obrigatório): Índice da linha (baseado em 0) da célula de referência.
|
||||
- `columnIndex` (integer, opcional): Índice da coluna (baseado em 0) da célula de referência. Padrão: `0`.
|
||||
- `insertBelow` (boolean, opcional): Se `true`, insere abaixo da linha de referência. Se `false`, insere acima. Padrão: `true`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_table_column">
|
||||
**Descrição:** Inserir uma nova coluna à esquerda ou à direita de uma célula de referência em uma tabela existente.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `tableStartIndex` (integer, obrigatório): O índice inicial da tabela.
|
||||
- `rowIndex` (integer, opcional): Índice da linha (baseado em 0) da célula de referência. Padrão: `0`.
|
||||
- `columnIndex` (integer, obrigatório): Índice da coluna (baseado em 0) da célula de referência.
|
||||
- `insertRight` (boolean, opcional): Se `true`, insere à direita. Se `false`, insere à esquerda. Padrão: `true`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/delete_table_row">
|
||||
**Descrição:** Excluir uma linha de uma tabela existente em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `tableStartIndex` (integer, obrigatório): O índice inicial da tabela.
|
||||
- `rowIndex` (integer, obrigatório): Índice da linha (baseado em 0) a excluir.
|
||||
- `columnIndex` (integer, opcional): Índice da coluna (baseado em 0) de qualquer célula na linha. Padrão: `0`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/delete_table_column">
|
||||
**Descrição:** Excluir uma coluna de uma tabela existente em um documento do Google.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `tableStartIndex` (integer, obrigatório): O índice inicial da tabela.
|
||||
- `rowIndex` (integer, opcional): Índice da linha (baseado em 0) de qualquer célula na coluna. Padrão: `0`.
|
||||
- `columnIndex` (integer, obrigatório): Índice da coluna (baseado em 0) a excluir.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/merge_table_cells">
|
||||
**Descrição:** Mesclar um intervalo de células de tabela em uma única célula. O conteúdo de todas as células é preservado.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `tableStartIndex` (integer, obrigatório): O índice inicial da tabela.
|
||||
- `rowIndex` (integer, obrigatório): Índice da linha inicial (baseado em 0) para a mesclagem.
|
||||
- `columnIndex` (integer, obrigatório): Índice da coluna inicial (baseado em 0) para a mesclagem.
|
||||
- `rowSpan` (integer, obrigatório): Número de linhas a mesclar.
|
||||
- `columnSpan` (integer, obrigatório): Número de colunas a mesclar.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/unmerge_table_cells">
|
||||
**Descrição:** Desfazer a mesclagem de células de tabela previamente mescladas, retornando-as a células individuais.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `tableStartIndex` (integer, obrigatório): O índice inicial da tabela.
|
||||
- `rowIndex` (integer, obrigatório): Índice da linha (baseado em 0) da célula mesclada.
|
||||
- `columnIndex` (integer, obrigatório): Índice da coluna (baseado em 0) da célula mesclada.
|
||||
- `rowSpan` (integer, obrigatório): Número de linhas que a célula mesclada abrange.
|
||||
- `columnSpan` (integer, obrigatório): Número de colunas que a célula mesclada abrange.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_inline_image">
|
||||
**Descrição:** Inserir uma imagem de uma URL pública em um documento do Google. A imagem deve ser publicamente acessível, ter menos de 50MB e estar no formato PNG/JPEG/GIF.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `uri` (string, obrigatório): URL pública da imagem. Deve ser acessível sem autenticação.
|
||||
- `index` (integer, opcional): Posição para inserir a imagem. Se não fornecido, a imagem é inserida no final do documento. Padrão: `1`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_section_break">
|
||||
**Descrição:** Inserir uma quebra de seção para criar seções de documento com formatação diferente.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `index` (integer, obrigatório): Posição para inserir a quebra de seção.
|
||||
- `sectionType` (string, obrigatório): O tipo de quebra de seção. Opções: `CONTINUOUS` (permanece na mesma página), `NEXT_PAGE` (inicia uma nova página).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/create_header">
|
||||
**Descrição:** Criar um cabeçalho para o documento. Retorna um headerId que pode ser usado com insert_text para adicionar conteúdo ao cabeçalho.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `type` (string, opcional): Tipo de cabeçalho. Opções: `DEFAULT`. Padrão: `DEFAULT`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/create_footer">
|
||||
**Descrição:** Criar um rodapé para o documento. Retorna um footerId que pode ser usado com insert_text para adicionar conteúdo ao rodapé.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `type` (string, opcional): Tipo de rodapé. Opções: `DEFAULT`. Padrão: `DEFAULT`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/delete_header">
|
||||
**Descrição:** Excluir um cabeçalho do documento. Use get_document para encontrar o headerId.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `headerId` (string, obrigatório): O ID do cabeçalho a excluir. Obtenha da resposta de get_document.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/delete_footer">
|
||||
**Descrição:** Excluir um rodapé do documento. Use get_document para encontrar o footerId.
|
||||
|
||||
**Parâmetros:**
|
||||
- `documentId` (string, obrigatório): O ID do documento.
|
||||
- `footerId` (string, obrigatório): O ID do rodapé a excluir. Obtenha da resposta de get_document.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Exemplos de Uso
|
||||
|
||||
### Configuração Básica do Agente Google Docs
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente com capacidades do Google Docs
|
||||
docs_agent = Agent(
|
||||
role="Criador de Documentos",
|
||||
goal="Criar e gerenciar documentos do Google Docs de forma eficiente",
|
||||
backstory="Um assistente IA especializado em criação e edição de documentos do Google Docs.",
|
||||
apps=['google_docs'] # Todas as ações do Google Docs estarão disponíveis
|
||||
)
|
||||
|
||||
# Tarefa para criar um novo documento
|
||||
create_doc_task = Task(
|
||||
description="Criar um novo documento do Google intitulado 'Relatório de Status do Projeto'",
|
||||
agent=docs_agent,
|
||||
expected_output="Novo documento do Google 'Relatório de Status do Projeto' criado com sucesso"
|
||||
)
|
||||
|
||||
# Execute a tarefa
|
||||
crew = Crew(
|
||||
agents=[docs_agent],
|
||||
tasks=[create_doc_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### Edição de Texto e Gerenciamento de Conteúdo
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente focado em edição de texto
|
||||
text_editor = Agent(
|
||||
role="Editor de Documentos",
|
||||
goal="Editar e atualizar conteúdo em documentos do Google Docs",
|
||||
backstory="Um assistente IA habilidoso em edição precisa de texto e gerenciamento de conteúdo.",
|
||||
apps=['google_docs/insert_text', 'google_docs/replace_text', 'google_docs/delete_content_range']
|
||||
)
|
||||
|
||||
# Tarefa para editar conteúdo do documento
|
||||
edit_content_task = Task(
|
||||
description="No documento 'your_document_id', inserir o texto 'Resumo Executivo: ' no início, depois substituir todas as instâncias de 'TODO' por 'CONCLUÍDO'.",
|
||||
agent=text_editor,
|
||||
expected_output="Documento atualizado com novo texto inserido e itens TODO substituídos."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[text_editor],
|
||||
tasks=[edit_content_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### Operações Avançadas de Documentos
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente para operações avançadas de documentos
|
||||
document_formatter = Agent(
|
||||
role="Formatador de Documentos",
|
||||
goal="Aplicar formatação avançada e estrutura a documentos do Google",
|
||||
backstory="Um assistente IA que lida com formatação complexa de documentos e organização.",
|
||||
apps=['google_docs/batch_update', 'google_docs/insert_page_break', 'google_docs/create_named_range']
|
||||
)
|
||||
|
||||
# Tarefa para formatar documento
|
||||
format_doc_task = Task(
|
||||
description="No documento 'your_document_id', inserir uma quebra de página na posição 100, criar um intervalo nomeado chamado 'Introdução' para caracteres 1-50, e aplicar atualizações de formatação em lote.",
|
||||
agent=document_formatter,
|
||||
expected_output="Documento formatado com quebra de página, intervalo nomeado e estilo aplicado."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[document_formatter],
|
||||
tasks=[format_doc_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Problemas Comuns
|
||||
|
||||
**Erros de Autenticação**
|
||||
|
||||
- Certifique-se de que sua conta Google tenha as permissões necessárias para acesso ao Google Docs.
|
||||
- Verifique se a conexão OAuth inclui todos os escopos necessários (`https://www.googleapis.com/auth/documents`).
|
||||
|
||||
**Problemas de ID do Documento**
|
||||
|
||||
- Verifique novamente os IDs dos documentos para correção.
|
||||
- Certifique-se de que o documento existe e está acessível à sua conta.
|
||||
- IDs de documentos podem ser encontrados na URL do Google Docs.
|
||||
|
||||
**Inserção de Texto e Operações de Intervalo**
|
||||
|
||||
- Ao usar `insert_text` ou `delete_content_range`, certifique-se de que as posições de índice sejam válidas.
|
||||
- Lembre-se de que o Google Docs usa indexação baseada em zero.
|
||||
- O documento deve ter conteúdo nas posições de índice especificadas.
|
||||
|
||||
**Formatação de Solicitação de Atualização em Lote**
|
||||
|
||||
- Ao usar `batch_update`, certifique-se de que o array `requests` esteja formatado corretamente de acordo com a documentação da API do Google Docs.
|
||||
- Atualizações complexas requerem estruturas JSON específicas para cada tipo de solicitação.
|
||||
|
||||
**Operações de Substituição de Texto**
|
||||
|
||||
- Para `replace_text`, certifique-se de que o parâmetro `containsText` corresponda exatamente ao texto que você deseja substituir.
|
||||
- Use o parâmetro `matchCase` para controlar a sensibilidade a maiúsculas e minúsculas.
|
||||
|
||||
### 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 com configuração
|
||||
ou solução de problemas da integração Google Docs.
|
||||
</Card>
|
||||
70
docs/edge/pt-BR/enterprise/integrations/google_drive.mdx
Normal file
70
docs/edge/pt-BR/enterprise/integrations/google_drive.mdx
Normal file
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Integração Google Drive
|
||||
description: "Gerenciamento de arquivos e pastas com integração Google Drive para CrewAI."
|
||||
icon: "google"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Permita que seus agentes acessem e gerenciem arquivos e pastas no Google Drive. Faça upload, download, organize conteúdo, crie links de compartilhamento e simplifique seus fluxos de trabalho de armazenamento em nuvem com automação alimentada por IA.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
Antes de usar a integração Google Drive, certifique-se de ter:
|
||||
|
||||
- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa
|
||||
- Uma conta Google com acesso ao Google Drive
|
||||
- Conectado sua conta Google através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
|
||||
|
||||
## Configurando a Integração Google Drive
|
||||
|
||||
### 1. Conecte sua Conta Google
|
||||
|
||||
1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors)
|
||||
2. Encontre **Google Drive** 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 a arquivos
|
||||
5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## Ações Disponíveis
|
||||
|
||||
Para informações detalhadas sobre parâmetros e uso, consulte a [documentação em inglês](../../../en/enterprise/integrations/google_drive).
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Problemas Comuns
|
||||
|
||||
**Erros de Autenticação**
|
||||
|
||||
- Certifique-se de que sua conta Google tenha as permissões necessárias para acesso ao Google Drive.
|
||||
|
||||
### 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 com configuração
|
||||
ou solução de problemas da integração Google Drive.
|
||||
</Card>
|
||||
327
docs/edge/pt-BR/enterprise/integrations/google_sheets.mdx
Normal file
327
docs/edge/pt-BR/enterprise/integrations/google_sheets.mdx
Normal file
@@ -0,0 +1,327 @@
|
||||
---
|
||||
title: Integração com Google Sheets
|
||||
description: "Sincronização de dados de planilhas com a integração do Google Sheets para CrewAI."
|
||||
icon: "google"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP](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 AMP](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 de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## Ações Disponíveis
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="google_sheets/get_values">
|
||||
**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/append_values">
|
||||
**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_values">
|
||||
**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
|
||||
|
||||
# Obtenha as ferramentas enterprise (ferramentas Google Sheets incluídas)
|
||||
|
||||
# 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.",
|
||||
apps=['google_sheets']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
# Obtenha apenas ferramentas específicas do Google Sheets
|
||||
actions_list=["google_sheets/get_values", "google_sheets/update_values"]
|
||||
)
|
||||
|
||||
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.",
|
||||
apps=['google_sheets']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['google_sheets']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['google_sheets']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['google_sheets']
|
||||
)
|
||||
|
||||
# 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>
|
||||
403
docs/edge/pt-BR/enterprise/integrations/google_slides.mdx
Normal file
403
docs/edge/pt-BR/enterprise/integrations/google_slides.mdx
Normal file
@@ -0,0 +1,403 @@
|
||||
---
|
||||
title: Integração Google Slides
|
||||
description: "Criação e gerenciamento de apresentações com integração Google Slides para CrewAI."
|
||||
icon: "chart-bar"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Permita que seus agentes criem, editem e gerenciem apresentações do Google Slides. Crie apresentações, atualize conteúdo, importe dados do Google Sheets, gerencie páginas e miniaturas, e simplifique seus fluxos de trabalho de apresentações com automação alimentada por IA.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
Antes de usar a integração Google Slides, certifique-se de ter:
|
||||
|
||||
- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa
|
||||
- Uma conta Google com acesso ao Google Slides
|
||||
- Conectado sua conta Google através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
|
||||
|
||||
## Configurando a Integração Google Slides
|
||||
|
||||
### 1. Conecte sua Conta Google
|
||||
|
||||
1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors)
|
||||
2. Encontre **Google Slides** 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 a apresentações, planilhas e drive
|
||||
5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## Ações Disponíveis
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="google_slides/create_blank_presentation">
|
||||
**Descrição:** Cria uma apresentação em branco sem conteúdo.
|
||||
|
||||
**Parâmetros:**
|
||||
- `title` (string, obrigatório): O título da apresentação.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_presentation_metadata">
|
||||
**Descrição:** Obter metadados leves de uma apresentação (título, número de slides, IDs dos slides). Use isso primeiro antes de recuperar o conteúdo completo.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação a ser recuperada.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_presentation_text">
|
||||
**Descrição:** Extrair todo o conteúdo de texto de uma apresentação. Retorna IDs dos slides e texto de formas e tabelas apenas (sem formatação).
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_presentation">
|
||||
**Descrição:** Recupera uma apresentação por ID.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação a ser recuperada.
|
||||
- `fields` (string, opcional): Os campos a incluir na resposta. Use isso para melhorar o desempenho retornando apenas os dados necessários.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/batch_update_presentation">
|
||||
**Descrição:** Aplica atualizações, adiciona conteúdo ou remove conteúdo de uma apresentação.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação a ser atualizada.
|
||||
- `requests` (array, obrigatório): Uma lista de atualizações a aplicar à apresentação. Cada item é um objeto representando uma solicitação.
|
||||
- `writeControl` (object, opcional): Fornece controle sobre como as solicitações de escrita são executadas. Contém `requiredRevisionId` (string).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_slide_text">
|
||||
**Descrição:** Extrair conteúdo de texto de um único slide. Retorna apenas texto de formas e tabelas (sem formatação ou estilo).
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `pageObjectId` (string, obrigatório): O ID do slide/página para obter o texto.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_page">
|
||||
**Descrição:** Recupera uma página específica por seu ID.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `pageObjectId` (string, obrigatório): O ID da página a ser recuperada.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_thumbnail">
|
||||
**Descrição:** Gera uma miniatura da página.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `pageObjectId` (string, obrigatório): O ID da página para geração de miniatura.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/create_slide">
|
||||
**Descrição:** Adicionar um slide em branco adicional a uma apresentação. Novas apresentações já possuem um slide em branco - verifique get_presentation_metadata primeiro. Para slides com áreas de título/corpo, use create_slide_with_layout.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `insertionIndex` (integer, opcional): Onde inserir o slide (baseado em 0). Se omitido, adiciona no final.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/create_slide_with_layout">
|
||||
**Descrição:** Criar um slide com layout predefinido contendo áreas de espaço reservado para título, corpo, etc. Melhor que create_slide para conteúdo estruturado. Após criar, use get_page para encontrar os IDs de espaço reservado, depois insira texto neles.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `layout` (string, obrigatório): Tipo de layout. Um de: `BLANK`, `TITLE`, `TITLE_AND_BODY`, `TITLE_AND_TWO_COLUMNS`, `TITLE_ONLY`, `SECTION_HEADER`, `ONE_COLUMN_TEXT`, `MAIN_POINT`, `BIG_NUMBER`. TITLE_AND_BODY é melhor para título+descrição. TITLE para slides apenas com título. SECTION_HEADER para divisores de seção.
|
||||
- `insertionIndex` (integer, opcional): Onde inserir (baseado em 0). Se omitido, adiciona no final.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/create_text_box">
|
||||
**Descrição:** Criar uma caixa de texto em um slide com conteúdo. Use para títulos, descrições, parágrafos - não para tabelas. Opcionalmente especifique posição (x, y) e tamanho (width, height) em unidades EMU (914400 EMU = 1 polegada).
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `slideId` (string, obrigatório): O ID do slide para adicionar a caixa de texto.
|
||||
- `text` (string, obrigatório): O conteúdo de texto da caixa de texto.
|
||||
- `x` (integer, opcional): Posição X em EMU (914400 = 1 polegada). Padrão: 914400 (1 polegada da esquerda).
|
||||
- `y` (integer, opcional): Posição Y em EMU (914400 = 1 polegada). Padrão: 914400 (1 polegada do topo).
|
||||
- `width` (integer, opcional): Largura em EMU. Padrão: 7315200 (~8 polegadas).
|
||||
- `height` (integer, opcional): Altura em EMU. Padrão: 914400 (~1 polegada).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/delete_slide">
|
||||
**Descrição:** Remover um slide de uma apresentação. Use get_presentation primeiro para encontrar o ID do slide.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `slideId` (string, obrigatório): O ID do objeto do slide a excluir. Obtenha de get_presentation.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/duplicate_slide">
|
||||
**Descrição:** Criar uma cópia de um slide existente. A duplicata é inserida imediatamente após o original.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `slideId` (string, obrigatório): O ID do objeto do slide a duplicar. Obtenha de get_presentation.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/move_slides">
|
||||
**Descrição:** Reordenar slides movendo-os para uma nova posição. Os IDs dos slides devem estar na ordem atual da apresentação (sem duplicatas).
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `slideIds` (array de strings, obrigatório): Array de IDs dos slides a mover. Obrigatoriamente na ordem atual da apresentação.
|
||||
- `insertionIndex` (integer, obrigatório): Posição de destino (baseado em 0). 0 = início, número de slides = final.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/insert_youtube_video">
|
||||
**Descrição:** Incorporar um vídeo do YouTube em um slide. O ID do vídeo é o valor após "v=" nas URLs do YouTube (ex: para youtube.com/watch?v=abc123, use "abc123").
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `slideId` (string, obrigatório): O ID do slide para adicionar o vídeo. Obtenha de get_presentation.
|
||||
- `videoId` (string, obrigatório): O ID do vídeo do YouTube (o valor após v= na URL).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/insert_drive_video">
|
||||
**Descrição:** Incorporar um vídeo do Google Drive em um slide. O ID do arquivo pode ser encontrado na URL do arquivo no Drive.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `slideId` (string, obrigatório): O ID do slide para adicionar o vídeo. Obtenha de get_presentation.
|
||||
- `fileId` (string, obrigatório): O ID do arquivo do Google Drive do vídeo.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/set_slide_background_image">
|
||||
**Descrição:** Definir uma imagem de fundo para um slide. A URL da imagem deve ser publicamente acessível.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `slideId` (string, obrigatório): O ID do slide para definir o fundo. Obtenha de get_presentation.
|
||||
- `imageUrl` (string, obrigatório): URL publicamente acessível da imagem a usar como fundo.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/create_table">
|
||||
**Descrição:** Criar uma tabela vazia em um slide. Para criar uma tabela com conteúdo, use create_table_with_content.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `slideId` (string, obrigatório): O ID do slide para adicionar a tabela. Obtenha de get_presentation.
|
||||
- `rows` (integer, obrigatório): Número de linhas na tabela.
|
||||
- `columns` (integer, obrigatório): Número de colunas na tabela.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/create_table_with_content">
|
||||
**Descrição:** Criar uma tabela com conteúdo em uma única ação. Forneça o conteúdo como uma matriz 2D onde cada array interno é uma linha. Exemplo: [["Cabeçalho1", "Cabeçalho2"], ["Linha1Col1", "Linha1Col2"]].
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `slideId` (string, obrigatório): O ID do slide para adicionar a tabela. Obtenha de get_presentation.
|
||||
- `rows` (integer, obrigatório): Número de linhas na tabela.
|
||||
- `columns` (integer, obrigatório): Número de colunas na tabela.
|
||||
- `content` (array, obrigatório): Conteúdo da tabela como matriz 2D. Cada array interno é uma linha. Exemplo: [["Ano", "Receita"], ["2023", "$10M"]].
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/import_data_from_sheet">
|
||||
**Descrição:** Importa dados de uma planilha do Google para uma apresentação.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `sheetId` (string, obrigatório): O ID da planilha do Google para importar.
|
||||
- `dataRange` (string, obrigatório): O intervalo de dados a importar da planilha.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/upload_file_to_drive">
|
||||
**Descrição:** Faz upload de um arquivo para o Google Drive associado à apresentação.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file` (string, obrigatório): Os dados do arquivo a fazer upload.
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação para vincular o arquivo carregado.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/link_file_to_presentation">
|
||||
**Descrição:** Vincula um arquivo no Google Drive a uma apresentação.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação.
|
||||
- `fileId` (string, obrigatório): O ID do arquivo a vincular.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_all_presentations">
|
||||
**Descrição:** Lista todas as apresentações acessíveis ao usuário.
|
||||
|
||||
**Parâmetros:**
|
||||
- `pageSize` (integer, opcional): O número de apresentações a retornar por página.
|
||||
- `pageToken` (string, opcional): Um token para paginação.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/delete_presentation">
|
||||
**Descrição:** Exclui uma apresentação por ID.
|
||||
|
||||
**Parâmetros:**
|
||||
- `presentationId` (string, obrigatório): O ID da apresentação a ser excluída.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Exemplos de Uso
|
||||
|
||||
### Configuração Básica do Agente Google Slides
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente com capacidades do Google Slides
|
||||
slides_agent = Agent(
|
||||
role="Criador de Apresentações",
|
||||
goal="Criar e gerenciar apresentações do Google Slides de forma eficiente",
|
||||
backstory="Um assistente IA especializado em design de apresentações e gerenciamento de conteúdo.",
|
||||
apps=['google_slides'] # Todas as ações do Google Slides estarão disponíveis
|
||||
)
|
||||
|
||||
# Tarefa para criar uma nova apresentação
|
||||
create_presentation_task = Task(
|
||||
description="Criar uma nova apresentação em branco intitulada 'Relatório de Vendas Trimestral'",
|
||||
agent=slides_agent,
|
||||
expected_output="Nova apresentação 'Relatório de Vendas Trimestral' criada com sucesso"
|
||||
)
|
||||
|
||||
# Execute a tarefa
|
||||
crew = Crew(
|
||||
agents=[slides_agent],
|
||||
tasks=[create_presentation_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### Atualizando Conteúdo da Apresentação
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente focado em atualizar apresentações
|
||||
updater_agent = Agent(
|
||||
role="Atualizador de Apresentações",
|
||||
goal="Atualizar e modificar apresentações existentes do Google Slides",
|
||||
backstory="Um assistente IA habilidoso em fazer atualizações precisas no conteúdo de apresentações.",
|
||||
apps=['google_slides/batch_update_presentation']
|
||||
)
|
||||
|
||||
# Tarefa para atualizar uma apresentação
|
||||
update_presentation_task = Task(
|
||||
description="Atualizar a apresentação com ID 'your_presentation_id' para adicionar uma nova caixa de texto no primeiro slide com o conteúdo 'Destaques Principais'.",
|
||||
agent=updater_agent,
|
||||
expected_output="Apresentação atualizada com novo conteúdo."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[updater_agent],
|
||||
tasks=[update_presentation_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### Importando Dados e Gerenciando Arquivos
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente para importação de dados e gerenciamento de arquivos
|
||||
data_presenter = Agent(
|
||||
role="Apresentador de Dados",
|
||||
goal="Importar dados para apresentações e gerenciar arquivos vinculados",
|
||||
backstory="Um assistente IA que integra dados de várias fontes em apresentações.",
|
||||
apps=['google_slides/import_data_from_sheet', 'google_slides/upload_file_to_drive']
|
||||
)
|
||||
|
||||
# Tarefa para importar dados de uma planilha
|
||||
import_data_task = Task(
|
||||
description="Importar dados da planilha do Google 'your_sheet_id' intervalo 'A1:C10' para a apresentação 'your_presentation_id'.",
|
||||
agent=data_presenter,
|
||||
expected_output="Dados importados da planilha do Google para a apresentação."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[data_presenter],
|
||||
tasks=[import_data_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Problemas Comuns
|
||||
|
||||
**Erros de Autenticação**
|
||||
|
||||
- Certifique-se de que sua conta Google tenha as permissões necessárias para acesso ao Google Slides e Google Drive.
|
||||
- Verifique se a conexão OAuth inclui todos os escopos necessários.
|
||||
|
||||
**Problemas de ID de Apresentação/Página**
|
||||
|
||||
- Verifique novamente os IDs de apresentação e IDs de objeto de página para correção.
|
||||
- Certifique-se de que a apresentação ou página existe e está acessível.
|
||||
|
||||
**Formatação de Solicitação de Atualização em Lote**
|
||||
|
||||
- Ao usar `batch_update_presentation`, certifique-se de que o array `requests` esteja formatado corretamente de acordo com a documentação da API do Google Slides.
|
||||
- Atualizações complexas frequentemente requerem estruturas JSON específicas para cada tipo de solicitação (ex: `createText`, `insertShape`).
|
||||
|
||||
**Problemas de Upload/Vinculação de Arquivos**
|
||||
|
||||
- Certifique-se de que o conteúdo do `file` esteja fornecido corretamente para `upload_file_to_drive`.
|
||||
- Verifique se o `fileId` está correto ao vincular arquivos a uma apresentação.
|
||||
- Verifique as permissões do Google Drive para acesso a arquivos.
|
||||
|
||||
### 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 com configuração
|
||||
ou solução de problemas da integração Google Slides.
|
||||
</Card>
|
||||
618
docs/edge/pt-BR/enterprise/integrations/hubspot.mdx
Normal file
618
docs/edge/pt-BR/enterprise/integrations/hubspot.mdx
Normal file
@@ -0,0 +1,618 @@
|
||||
---
|
||||
title: "Integração com HubSpot"
|
||||
description: "Gerencie empresas e contatos no HubSpot com o CrewAI."
|
||||
icon: "briefcase"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP](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 AMP 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 de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## Ações Disponíveis
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="hubspot/create_company">
|
||||
**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_contact">
|
||||
**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_deal">
|
||||
**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_company">
|
||||
**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_contact">
|
||||
**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_deal">
|
||||
**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/list_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/list_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/list_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_company">
|
||||
**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_contact">
|
||||
**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_deal">
|
||||
**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_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_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_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
|
||||
|
||||
# Obtenha as ferramentas enterprise (ferramentas HubSpot incluídas)
|
||||
|
||||
# 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.",
|
||||
apps=['hubspot']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
# Obtenha somente a ferramenta para criar contatos
|
||||
actions_list=["hubspot/create_contact"]
|
||||
)
|
||||
|
||||
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.",
|
||||
apps=['hubspot']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
crm_manager = Agent(
|
||||
role="CRM Manager",
|
||||
goal="Manage and organize HubSpot contacts efficiently.",
|
||||
backstory="An experienced CRM manager who maintains an organized contact database.",
|
||||
apps=['hubspot']
|
||||
)
|
||||
|
||||
# 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>
|
||||
392
docs/edge/pt-BR/enterprise/integrations/jira.mdx
Normal file
392
docs/edge/pt-BR/enterprise/integrations/jira.mdx
Normal file
@@ -0,0 +1,392 @@
|
||||
---
|
||||
title: Integração com Jira
|
||||
description: "Rastreamento de problemas e gestão de projetos com a integração Jira para CrewAI."
|
||||
icon: "bug"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP](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 AMP](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 de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 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
|
||||
|
||||
# Obtenha as ferramentas enterprise (incluirá ferramentas do Jira)
|
||||
|
||||
# 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.",
|
||||
apps=['jira']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
# Obtenha apenas ferramentas Jira específicas
|
||||
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.",
|
||||
apps=['jira']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['jira']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['jira']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['jira']
|
||||
)
|
||||
|
||||
# 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>
|
||||
470
docs/edge/pt-BR/enterprise/integrations/linear.mdx
Normal file
470
docs/edge/pt-BR/enterprise/integrations/linear.mdx
Normal file
@@ -0,0 +1,470 @@
|
||||
---
|
||||
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"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP](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 AMP](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 de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
# Obtenha ferramentas empresariais (ferramentas do Linear serão incluídas)
|
||||
|
||||
# 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.",
|
||||
apps=['linear']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
# Obtenha apenas ferramentas lineares específicas
|
||||
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.",
|
||||
apps=['linear']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['linear']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['linear']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['linear']
|
||||
)
|
||||
|
||||
# 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>
|
||||
289
docs/edge/pt-BR/enterprise/integrations/microsoft_excel.mdx
Normal file
289
docs/edge/pt-BR/enterprise/integrations/microsoft_excel.mdx
Normal file
@@ -0,0 +1,289 @@
|
||||
---
|
||||
title: Integração Microsoft Excel
|
||||
description: "Gerenciamento de pastas de trabalho e dados com integração Microsoft Excel para CrewAI."
|
||||
icon: "table"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Permita que seus agentes criem e gerenciem pastas de trabalho, planilhas, tabelas e gráficos do Excel no OneDrive ou SharePoint. Manipule intervalos de dados, crie visualizações, gerencie tabelas e simplifique seus fluxos de trabalho de planilhas com automação alimentada por IA.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
Antes de usar a integração Microsoft Excel, certifique-se de ter:
|
||||
|
||||
- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa
|
||||
- Uma conta Microsoft 365 com acesso ao Excel e OneDrive/SharePoint
|
||||
- Conectado sua conta Microsoft através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
|
||||
|
||||
## Configurando a Integração Microsoft Excel
|
||||
|
||||
### 1. Conecte sua Conta Microsoft
|
||||
|
||||
1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors)
|
||||
2. Encontre **Microsoft Excel** 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 a arquivos e pastas de trabalho do Excel
|
||||
5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## Ações Disponíveis
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="microsoft_excel/create_workbook">
|
||||
**Descrição:** Criar uma nova pasta de trabalho do Excel no OneDrive ou SharePoint.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_path` (string, obrigatório): Caminho onde criar a pasta de trabalho (ex: 'MinhaPastaDeTrabalho.xlsx')
|
||||
- `worksheets` (array, opcional): Planilhas iniciais para criar. Cada item é um objeto com `name` (string, nome da planilha).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_workbooks">
|
||||
**Descrição:** Obter todas as pastas de trabalho do Excel do OneDrive ou SharePoint.
|
||||
|
||||
**Parâmetros:**
|
||||
- `select` (string, opcional): Selecionar propriedades específicas para retornar.
|
||||
- `filter` (string, opcional): Filtrar resultados usando sintaxe OData.
|
||||
- `expand` (string, opcional): Expandir recursos relacionados inline.
|
||||
- `top` (integer, opcional): Número de itens a retornar (mín 1, máx 999).
|
||||
- `orderby` (string, opcional): Ordenar resultados por propriedades especificadas.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_worksheets">
|
||||
**Descrição:** Obter todas as planilhas em uma pasta de trabalho do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `select` (string, opcional): Selecionar propriedades específicas para retornar (ex: 'id,name,position').
|
||||
- `filter` (string, opcional): Filtrar resultados usando sintaxe OData.
|
||||
- `expand` (string, opcional): Expandir recursos relacionados inline.
|
||||
- `top` (integer, opcional): Número de itens a retornar (mín 1, máx 999).
|
||||
- `orderby` (string, opcional): Ordenar resultados por propriedades especificadas.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/create_worksheet">
|
||||
**Descrição:** Criar uma nova planilha em uma pasta de trabalho do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `name` (string, obrigatório): Nome da nova planilha.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_range_data">
|
||||
**Descrição:** Obter dados de um intervalo específico em uma planilha do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha.
|
||||
- `range` (string, obrigatório): Endereço do intervalo (ex: 'A1:C10').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/update_range_data">
|
||||
**Descrição:** Atualizar dados em um intervalo específico em uma planilha do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha.
|
||||
- `range` (string, obrigatório): Endereço do intervalo (ex: 'A1:C10').
|
||||
- `values` (array, obrigatório): Array 2D de valores para definir no intervalo. Cada array interno representa uma linha, e elementos podem ser string, number ou integer.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/add_table">
|
||||
**Descrição:** Criar uma tabela em uma planilha do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha.
|
||||
- `range` (string, obrigatório): Intervalo para a tabela (ex: 'A1:D10').
|
||||
- `has_headers` (boolean, opcional): Se a primeira linha contém cabeçalhos. Padrão: true.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_tables">
|
||||
**Descrição:** Obter todas as tabelas em uma planilha do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/add_table_row">
|
||||
**Descrição:** Adicionar uma nova linha a uma tabela do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha.
|
||||
- `table_name` (string, obrigatório): Nome da tabela.
|
||||
- `values` (array, obrigatório): Array de valores para a nova linha. Elementos podem ser string, number ou integer.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_table_data">
|
||||
**Descrição:** Obter dados de uma tabela específica em uma planilha do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha.
|
||||
- `table_name` (string, obrigatório): Nome da tabela.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/create_chart">
|
||||
**Descrição:** Criar um gráfico em uma planilha do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha.
|
||||
- `chart_type` (string, obrigatório): Tipo de gráfico (ex: 'ColumnClustered', 'Line', 'Pie').
|
||||
- `source_data` (string, obrigatório): Intervalo de dados para o gráfico (ex: 'A1:B10').
|
||||
- `series_by` (string, opcional): Como interpretar os dados ('Auto', 'Columns' ou 'Rows'). Padrão: 'Auto'.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_cell">
|
||||
**Descrição:** Obter o valor de uma única célula em uma planilha do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha.
|
||||
- `row` (integer, obrigatório): Número da linha (baseado em 0).
|
||||
- `column` (integer, obrigatório): Número da coluna (baseado em 0).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_used_range">
|
||||
**Descrição:** Obter o intervalo usado de uma planilha do Excel (contém todos os dados).
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_used_range_metadata">
|
||||
**Descrição:** Obter os metadados do intervalo usado (apenas dimensões, sem dados) de uma planilha do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/list_charts">
|
||||
**Descrição:** Obter todos os gráficos em uma planilha do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/delete_worksheet">
|
||||
**Descrição:** Excluir uma planilha de uma pasta de trabalho do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha a excluir.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/delete_table">
|
||||
**Descrição:** Excluir uma tabela de uma planilha do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha.
|
||||
- `table_name` (string, obrigatório): Nome da tabela a excluir.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/list_names">
|
||||
**Descrição:** Obter todos os intervalos nomeados em uma pasta de trabalho do Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do arquivo Excel.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Exemplos de Uso
|
||||
|
||||
### Configuração Básica do Agente Microsoft Excel
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente com capacidades do Microsoft Excel
|
||||
excel_agent = Agent(
|
||||
role="Gerenciador de Dados Excel",
|
||||
goal="Gerenciar pastas de trabalho e dados do Excel de forma eficiente",
|
||||
backstory="Um assistente IA especializado em operações do Microsoft Excel e manipulação de dados.",
|
||||
apps=['microsoft_excel'] # Todas as ações do Excel estarão disponíveis
|
||||
)
|
||||
|
||||
# Tarefa para criar uma nova pasta de trabalho
|
||||
create_workbook_task = Task(
|
||||
description="Criar uma nova pasta de trabalho do Excel chamada 'RelatorioMensal.xlsx' com uma planilha inicial chamada 'DadosVendas'.",
|
||||
agent=excel_agent,
|
||||
expected_output="Nova pasta de trabalho 'RelatorioMensal.xlsx' criada com planilha 'DadosVendas'."
|
||||
)
|
||||
|
||||
# Execute a tarefa
|
||||
crew = Crew(
|
||||
agents=[excel_agent],
|
||||
tasks=[create_workbook_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Problemas Comuns
|
||||
|
||||
**Erros de Autenticação**
|
||||
|
||||
- Certifique-se de que sua conta Microsoft tenha as permissões necessárias para acesso a arquivos (ex: `Files.Read.All`, `Files.ReadWrite.All`).
|
||||
- Verifique se a conexão OAuth inclui todos os escopos necessários.
|
||||
|
||||
**Problemas de Criação de Arquivos**
|
||||
|
||||
- Ao criar pastas de trabalho, certifique-se de que o `file_path` termine com extensão `.xlsx`.
|
||||
- Verifique se você tem permissões de escrita no local de destino (OneDrive/SharePoint).
|
||||
|
||||
### 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 com configuração
|
||||
ou solução de problemas da integração Microsoft Excel.
|
||||
</Card>
|
||||
249
docs/edge/pt-BR/enterprise/integrations/microsoft_onedrive.mdx
Normal file
249
docs/edge/pt-BR/enterprise/integrations/microsoft_onedrive.mdx
Normal file
@@ -0,0 +1,249 @@
|
||||
---
|
||||
title: Integração Microsoft OneDrive
|
||||
description: "Gerenciamento de arquivos e pastas com integração Microsoft OneDrive para CrewAI."
|
||||
icon: "cloud"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Permita que seus agentes façam upload, download e gerenciem arquivos e pastas no Microsoft OneDrive. Automatize operações de arquivos, organize conteúdo, crie links de compartilhamento e simplifique seus fluxos de trabalho de armazenamento em nuvem com automação alimentada por IA.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
Antes de usar a integração Microsoft OneDrive, certifique-se de ter:
|
||||
|
||||
- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa
|
||||
- Uma conta Microsoft com acesso ao OneDrive
|
||||
- Conectado sua conta Microsoft através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
|
||||
|
||||
## Configurando a Integração Microsoft OneDrive
|
||||
|
||||
### 1. Conecte sua Conta Microsoft
|
||||
|
||||
1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors)
|
||||
2. Encontre **Microsoft OneDrive** 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 a arquivos
|
||||
5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## Ações Disponíveis
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="microsoft_onedrive/list_files">
|
||||
**Descrição:** Listar arquivos e pastas no OneDrive.
|
||||
|
||||
**Parâmetros:**
|
||||
- `top` (integer, opcional): Número de itens a recuperar (máx 1000). Padrão: 50.
|
||||
- `orderby` (string, opcional): Ordenar por campo (ex: "name asc", "lastModifiedDateTime desc"). Padrão: "name asc".
|
||||
- `filter` (string, opcional): Expressão de filtro OData.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/get_file_info">
|
||||
**Descrição:** Obter informações sobre um arquivo ou pasta específica.
|
||||
|
||||
**Parâmetros:**
|
||||
- `item_id` (string, obrigatório): O ID do arquivo ou pasta.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/download_file">
|
||||
**Descrição:** Baixar um arquivo do OneDrive.
|
||||
|
||||
**Parâmetros:**
|
||||
- `item_id` (string, obrigatório): O ID do arquivo a baixar.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/upload_file">
|
||||
**Descrição:** Fazer upload de um arquivo para o OneDrive.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_name` (string, obrigatório): Nome do arquivo a fazer upload.
|
||||
- `content` (string, obrigatório): Conteúdo do arquivo codificado em Base64.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/create_folder">
|
||||
**Descrição:** Criar uma nova pasta no OneDrive.
|
||||
|
||||
**Parâmetros:**
|
||||
- `folder_name` (string, obrigatório): Nome da pasta a criar.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/delete_item">
|
||||
**Descrição:** Excluir um arquivo ou pasta do OneDrive.
|
||||
|
||||
**Parâmetros:**
|
||||
- `item_id` (string, obrigatório): O ID do arquivo ou pasta a excluir.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/copy_item">
|
||||
**Descrição:** Copiar um arquivo ou pasta no OneDrive.
|
||||
|
||||
**Parâmetros:**
|
||||
- `item_id` (string, obrigatório): O ID do arquivo ou pasta a copiar.
|
||||
- `parent_id` (string, opcional): O ID da pasta de destino (opcional, padrão para raiz).
|
||||
- `new_name` (string, opcional): Novo nome para o item copiado (opcional).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/move_item">
|
||||
**Descrição:** Mover um arquivo ou pasta no OneDrive.
|
||||
|
||||
**Parâmetros:**
|
||||
- `item_id` (string, obrigatório): O ID do arquivo ou pasta a mover.
|
||||
- `parent_id` (string, obrigatório): O ID da pasta de destino.
|
||||
- `new_name` (string, opcional): Novo nome para o item (opcional).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/search_files">
|
||||
**Descrição:** Pesquisar arquivos e pastas no OneDrive.
|
||||
|
||||
**Parâmetros:**
|
||||
- `query` (string, obrigatório): String de consulta de pesquisa.
|
||||
- `top` (integer, opcional): Número de resultados a retornar (máx 1000). Padrão: 50.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/share_item">
|
||||
**Descrição:** Criar um link de compartilhamento para um arquivo ou pasta.
|
||||
|
||||
**Parâmetros:**
|
||||
- `item_id` (string, obrigatório): O ID do arquivo ou pasta a compartilhar.
|
||||
- `type` (string, opcional): Tipo de link de compartilhamento. Opções: view, edit, embed. Padrão: view.
|
||||
- `scope` (string, opcional): Escopo do link de compartilhamento. Opções: anonymous, organization. Padrão: anonymous.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/get_thumbnails">
|
||||
**Descrição:** Obter miniaturas para um arquivo.
|
||||
|
||||
**Parâmetros:**
|
||||
- `item_id` (string, obrigatório): O ID do arquivo.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/list_files_by_path">
|
||||
**Descrição:** Listar arquivos e pastas em um caminho específico do OneDrive.
|
||||
|
||||
**Parâmetros:**
|
||||
- `folder_path` (string, obrigatório): O caminho da pasta (ex: 'Documents/Reports').
|
||||
- `top` (integer, opcional): Número de itens a recuperar (máx 1000). Padrão: 50.
|
||||
- `orderby` (string, opcional): Ordenar por campo (ex: "name asc", "lastModifiedDateTime desc"). Padrão: "name asc".
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/get_recent_files">
|
||||
**Descrição:** Obter arquivos acessados recentemente no OneDrive.
|
||||
|
||||
**Parâmetros:**
|
||||
- `top` (integer, opcional): Número de itens a recuperar (máx 200). Padrão: 25.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/get_shared_with_me">
|
||||
**Descrição:** Obter arquivos e pastas compartilhados com o usuário.
|
||||
|
||||
**Parâmetros:**
|
||||
- `top` (integer, opcional): Número de itens a recuperar (máx 200). Padrão: 50.
|
||||
- `orderby` (string, opcional): Ordenar por campo. Padrão: "name asc".
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/get_file_by_path">
|
||||
**Descrição:** Obter informações sobre um arquivo ou pasta específica pelo caminho.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_path` (string, obrigatório): O caminho do arquivo ou pasta (ex: 'Documents/report.docx').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/download_file_by_path">
|
||||
**Descrição:** Baixar um arquivo do OneDrive pelo seu caminho.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_path` (string, obrigatório): O caminho do arquivo (ex: 'Documents/report.docx').
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Exemplos de Uso
|
||||
|
||||
### Configuração Básica do Agente Microsoft OneDrive
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente com capacidades do Microsoft OneDrive
|
||||
onedrive_agent = Agent(
|
||||
role="Gerenciador de Arquivos",
|
||||
goal="Gerenciar arquivos e pastas no OneDrive de forma eficiente",
|
||||
backstory="Um assistente IA especializado em operações de arquivos do Microsoft OneDrive e organização.",
|
||||
apps=['microsoft_onedrive'] # Todas as ações do OneDrive estarão disponíveis
|
||||
)
|
||||
|
||||
# Tarefa para listar arquivos e criar pasta
|
||||
organize_files_task = Task(
|
||||
description="Listar todos os arquivos no diretório raiz do meu OneDrive e criar uma nova pasta chamada 'Documentos do Projeto'.",
|
||||
agent=onedrive_agent,
|
||||
expected_output="Lista de arquivos exibida e nova pasta 'Documentos do Projeto' criada."
|
||||
)
|
||||
|
||||
# Execute a tarefa
|
||||
crew = Crew(
|
||||
agents=[onedrive_agent],
|
||||
tasks=[organize_files_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Problemas Comuns
|
||||
|
||||
**Erros de Autenticação**
|
||||
|
||||
- Certifique-se de que sua conta Microsoft tenha as permissões necessárias para acesso a arquivos (ex: `Files.Read`, `Files.ReadWrite`).
|
||||
- Verifique se a conexão OAuth inclui todos os escopos necessários.
|
||||
|
||||
**Problemas de Upload de Arquivos**
|
||||
|
||||
- Certifique-se de que `file_name` e `content` sejam fornecidos para uploads de arquivos.
|
||||
- O conteúdo deve ser codificado em Base64 para arquivos binários.
|
||||
- Verifique se você tem permissões de escrita no OneDrive.
|
||||
|
||||
### 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 com configuração
|
||||
ou solução de problemas da integração Microsoft OneDrive.
|
||||
</Card>
|
||||
255
docs/edge/pt-BR/enterprise/integrations/microsoft_outlook.mdx
Normal file
255
docs/edge/pt-BR/enterprise/integrations/microsoft_outlook.mdx
Normal file
@@ -0,0 +1,255 @@
|
||||
---
|
||||
title: Integração Microsoft Outlook
|
||||
description: "Gerenciamento de email, calendário e contatos com integração Microsoft Outlook para CrewAI."
|
||||
icon: "envelope"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Permita que seus agentes acessem e gerenciem emails, eventos de calendário e contatos do Outlook. Envie emails, recupere mensagens, gerencie eventos de calendário e organize contatos com automação alimentada por IA.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
Antes de usar a integração Microsoft Outlook, certifique-se de ter:
|
||||
|
||||
- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa
|
||||
- Uma conta Microsoft com acesso ao Outlook
|
||||
- Conectado sua conta Microsoft através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
|
||||
|
||||
## Configurando a Integração Microsoft Outlook
|
||||
|
||||
### 1. Conecte sua Conta Microsoft
|
||||
|
||||
1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors)
|
||||
2. Encontre **Microsoft Outlook** 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 a email, calendário e contatos
|
||||
5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## Ações Disponíveis
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="microsoft_outlook/get_messages">
|
||||
**Descrição:** Obter mensagens de email da caixa de correio do usuário.
|
||||
|
||||
**Parâmetros:**
|
||||
- `top` (integer, opcional): Número de mensagens a recuperar (máx 1000). Padrão: 10.
|
||||
- `filter` (string, opcional): Expressão de filtro OData (ex: "isRead eq false").
|
||||
- `search` (string, opcional): String de consulta de pesquisa.
|
||||
- `orderby` (string, opcional): Ordenar por campo (ex: "receivedDateTime desc"). Padrão: "receivedDateTime desc".
|
||||
- `select` (string, opcional): Selecionar propriedades específicas para retornar.
|
||||
- `expand` (string, opcional): Expandir recursos relacionados inline.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/send_email">
|
||||
**Descrição:** Enviar uma mensagem de email.
|
||||
|
||||
**Parâmetros:**
|
||||
- `to_recipients` (array, obrigatório): Array de endereços de email dos destinatários.
|
||||
- `cc_recipients` (array, opcional): Array de endereços de email dos destinatários em cópia.
|
||||
- `bcc_recipients` (array, opcional): Array de endereços de email dos destinatários em cópia oculta.
|
||||
- `subject` (string, obrigatório): Assunto do email.
|
||||
- `body` (string, obrigatório): Conteúdo do corpo do email.
|
||||
- `body_type` (string, opcional): Tipo de conteúdo do corpo. Opções: Text, HTML. Padrão: HTML.
|
||||
- `importance` (string, opcional): Nível de importância da mensagem. Opções: low, normal, high. Padrão: normal.
|
||||
- `reply_to` (array, opcional): Array de endereços de email para resposta.
|
||||
- `save_to_sent_items` (boolean, opcional): Se deve salvar a mensagem na pasta Itens Enviados. Padrão: true.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/get_calendar_events">
|
||||
**Descrição:** Obter eventos de calendário do calendário do usuário.
|
||||
|
||||
**Parâmetros:**
|
||||
- `top` (integer, opcional): Número de eventos a recuperar (máx 1000). Padrão: 10.
|
||||
- `skip` (integer, opcional): Número de eventos a pular. Padrão: 0.
|
||||
- `filter` (string, opcional): Expressão de filtro OData (ex: "start/dateTime ge '2024-01-01T00:00:00Z'").
|
||||
- `orderby` (string, opcional): Ordenar por campo (ex: "start/dateTime asc"). Padrão: "start/dateTime asc".
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/create_calendar_event">
|
||||
**Descrição:** Criar um novo evento de calendário.
|
||||
|
||||
**Parâmetros:**
|
||||
- `subject` (string, obrigatório): Assunto/título do evento.
|
||||
- `body` (string, opcional): Corpo/descrição do evento.
|
||||
- `start_datetime` (string, obrigatório): Data e hora de início no formato ISO 8601 (ex: '2024-01-20T10:00:00').
|
||||
- `end_datetime` (string, obrigatório): Data e hora de término no formato ISO 8601.
|
||||
- `timezone` (string, opcional): Fuso horário (ex: 'Pacific Standard Time'). Padrão: UTC.
|
||||
- `location` (string, opcional): Local do evento.
|
||||
- `attendees` (array, opcional): Array de endereços de email dos participantes.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/get_contacts">
|
||||
**Descrição:** Obter contatos do catálogo de endereços do usuário.
|
||||
|
||||
**Parâmetros:**
|
||||
- `top` (integer, opcional): Número de contatos a recuperar (máx 1000). Padrão: 10.
|
||||
- `skip` (integer, opcional): Número de contatos a pular. Padrão: 0.
|
||||
- `filter` (string, opcional): Expressão de filtro OData.
|
||||
- `orderby` (string, opcional): Ordenar por campo (ex: "displayName asc"). Padrão: "displayName asc".
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/create_contact">
|
||||
**Descrição:** Criar um novo contato no catálogo de endereços do usuário.
|
||||
|
||||
**Parâmetros:**
|
||||
- `displayName` (string, obrigatório): Nome de exibição do contato.
|
||||
- `givenName` (string, opcional): Primeiro nome do contato.
|
||||
- `surname` (string, opcional): Sobrenome do contato.
|
||||
- `emailAddresses` (array, opcional): Array de endereços de email. Cada item é um objeto com `address` (string) e `name` (string).
|
||||
- `businessPhones` (array, opcional): Array de números de telefone comerciais.
|
||||
- `homePhones` (array, opcional): Array de números de telefone residenciais.
|
||||
- `jobTitle` (string, opcional): Cargo do contato.
|
||||
- `companyName` (string, opcional): Nome da empresa do contato.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/get_message">
|
||||
**Descrição:** Obter uma mensagem de email específica por ID.
|
||||
|
||||
**Parâmetros:**
|
||||
- `message_id` (string, obrigatório): O identificador único da mensagem. Obter pela ação get_messages.
|
||||
- `select` (string, opcional): Lista separada por vírgulas de propriedades a retornar. Exemplo: "id,subject,body,from,receivedDateTime". Padrão: "id,subject,body,from,toRecipients,receivedDateTime".
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/reply_to_email">
|
||||
**Descrição:** Responder a uma mensagem de email.
|
||||
|
||||
**Parâmetros:**
|
||||
- `message_id` (string, obrigatório): O identificador único da mensagem a responder. Obter pela ação get_messages.
|
||||
- `comment` (string, obrigatório): O conteúdo da mensagem de resposta. Pode ser texto simples ou HTML. A mensagem original será citada abaixo deste conteúdo.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/forward_email">
|
||||
**Descrição:** Encaminhar uma mensagem de email.
|
||||
|
||||
**Parâmetros:**
|
||||
- `message_id` (string, obrigatório): O identificador único da mensagem a encaminhar. Obter pela ação get_messages.
|
||||
- `to_recipients` (array, obrigatório): Array de endereços de email dos destinatários. Exemplo: ["john@example.com", "jane@example.com"].
|
||||
- `comment` (string, opcional): Mensagem opcional a incluir acima do conteúdo encaminhado. Pode ser texto simples ou HTML.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/mark_message_read">
|
||||
**Descrição:** Marcar uma mensagem como lida ou não lida.
|
||||
|
||||
**Parâmetros:**
|
||||
- `message_id` (string, obrigatório): O identificador único da mensagem. Obter pela ação get_messages.
|
||||
- `is_read` (boolean, obrigatório): Definir como true para marcar como lida, false para marcar como não lida.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/delete_message">
|
||||
**Descrição:** Excluir uma mensagem de email.
|
||||
|
||||
**Parâmetros:**
|
||||
- `message_id` (string, obrigatório): O identificador único da mensagem a excluir. Obter pela ação get_messages.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/update_event">
|
||||
**Descrição:** Atualizar um evento de calendário existente.
|
||||
|
||||
**Parâmetros:**
|
||||
- `event_id` (string, obrigatório): O identificador único do evento. Obter pela ação get_calendar_events.
|
||||
- `subject` (string, opcional): Novo assunto/título do evento.
|
||||
- `start_time` (string, opcional): Nova hora de início no formato ISO 8601 (ex: "2024-01-20T10:00:00"). OBRIGATÓRIO: Também deve fornecer start_timezone ao usar este campo.
|
||||
- `start_timezone` (string, opcional): Fuso horário da hora de início. OBRIGATÓRIO ao atualizar start_time. Exemplos: "Pacific Standard Time", "Eastern Standard Time", "UTC".
|
||||
- `end_time` (string, opcional): Nova hora de término no formato ISO 8601. OBRIGATÓRIO: Também deve fornecer end_timezone ao usar este campo.
|
||||
- `end_timezone` (string, opcional): Fuso horário da hora de término. OBRIGATÓRIO ao atualizar end_time. Exemplos: "Pacific Standard Time", "Eastern Standard Time", "UTC".
|
||||
- `location` (string, opcional): Novo local do evento.
|
||||
- `body` (string, opcional): Novo corpo/descrição do evento. Suporta formatação HTML.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/delete_event">
|
||||
**Descrição:** Excluir um evento de calendário.
|
||||
|
||||
**Parâmetros:**
|
||||
- `event_id` (string, obrigatório): O identificador único do evento a excluir. Obter pela ação get_calendar_events.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Exemplos de Uso
|
||||
|
||||
### Configuração Básica do Agente Microsoft Outlook
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente com capacidades do Microsoft Outlook
|
||||
outlook_agent = Agent(
|
||||
role="Assistente de Email",
|
||||
goal="Gerenciar emails, eventos de calendário e contatos de forma eficiente",
|
||||
backstory="Um assistente IA especializado em operações do Microsoft Outlook e gerenciamento de comunicação.",
|
||||
apps=['microsoft_outlook'] # Todas as ações do Outlook estarão disponíveis
|
||||
)
|
||||
|
||||
# Tarefa para enviar um email
|
||||
send_email_task = Task(
|
||||
description="Enviar um email para 'colega@exemplo.com' com assunto 'Atualização do Projeto' e corpo 'Olá, aqui está a última atualização do projeto. Atenciosamente.'",
|
||||
agent=outlook_agent,
|
||||
expected_output="Email enviado com sucesso para colega@exemplo.com"
|
||||
)
|
||||
|
||||
# Execute a tarefa
|
||||
crew = Crew(
|
||||
agents=[outlook_agent],
|
||||
tasks=[send_email_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Problemas Comuns
|
||||
|
||||
**Erros de Autenticação**
|
||||
|
||||
- Certifique-se de que sua conta Microsoft tenha as permissões necessárias para acesso a email, calendário e contatos.
|
||||
- Escopos necessários incluem: `Mail.Read`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`.
|
||||
|
||||
**Problemas de Envio de Email**
|
||||
|
||||
- Certifique-se de que `to_recipients`, `subject` e `body` sejam fornecidos para `send_email`.
|
||||
- Verifique se os endereços de email estão formatados corretamente.
|
||||
|
||||
### 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 com configuração
|
||||
ou solução de problemas da integração Microsoft Outlook.
|
||||
</Card>
|
||||
524
docs/edge/pt-BR/enterprise/integrations/microsoft_sharepoint.mdx
Normal file
524
docs/edge/pt-BR/enterprise/integrations/microsoft_sharepoint.mdx
Normal file
@@ -0,0 +1,524 @@
|
||||
---
|
||||
title: Integração Microsoft SharePoint
|
||||
description: "Gerenciamento de sites, listas e documentos com integração Microsoft SharePoint para CrewAI."
|
||||
icon: "folder-tree"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Permita que seus agentes acessem e gerenciem sites, listas e bibliotecas de documentos do SharePoint. Recupere informações do site, gerencie itens de lista, faça upload e organize arquivos, e simplifique seus fluxos de trabalho do SharePoint com automação alimentada por IA.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
Antes de usar a integração Microsoft SharePoint, certifique-se de ter:
|
||||
|
||||
- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa
|
||||
- Uma conta Microsoft com acesso ao SharePoint
|
||||
- Conectado sua conta Microsoft através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
|
||||
|
||||
## Configurando a Integração Microsoft SharePoint
|
||||
|
||||
### 1. Conecte sua Conta Microsoft
|
||||
|
||||
1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors)
|
||||
2. Encontre **Microsoft SharePoint** 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 a sites e arquivos do SharePoint
|
||||
5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## Ações Disponíveis
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="microsoft_sharepoint/get_sites">
|
||||
**Descrição:** Obter todos os sites do SharePoint aos quais o usuário tem acesso.
|
||||
|
||||
**Parâmetros:**
|
||||
- `search` (string, opcional): Consulta de pesquisa para filtrar sites.
|
||||
- `select` (string, opcional): Selecionar propriedades específicas para retornar (ex: 'displayName,id,webUrl').
|
||||
- `filter` (string, opcional): Filtrar resultados usando sintaxe OData.
|
||||
- `expand` (string, opcional): Expandir recursos relacionados inline.
|
||||
- `top` (integer, opcional): Número de itens a retornar (mín 1, máx 999).
|
||||
- `skip` (integer, opcional): Número de itens a pular (mín 0).
|
||||
- `orderby` (string, opcional): Ordenar resultados por propriedades especificadas (ex: 'displayName desc').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_site">
|
||||
**Descrição:** Obter informações sobre um site específico do SharePoint.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O ID do site do SharePoint.
|
||||
- `select` (string, opcional): Selecionar propriedades específicas para retornar (ex: 'displayName,id,webUrl,drives').
|
||||
- `expand` (string, opcional): Expandir recursos relacionados inline (ex: 'drives,lists').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_drives">
|
||||
**Descrição:** Listar todas as bibliotecas de documentos (drives) em um site do SharePoint. Use isto para descobrir bibliotecas disponíveis antes de usar operações de arquivo.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `top` (integer, opcional): Número máximo de drives a retornar por página (1-999). Padrão: 100
|
||||
- `skip_token` (string, opcional): Token de paginação de uma resposta anterior para buscar a próxima página de resultados.
|
||||
- `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'id,name,webUrl,driveType').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_site_lists">
|
||||
**Descrição:** Obter todas as listas em um site do SharePoint.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O ID do site do SharePoint.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_list">
|
||||
**Descrição:** Obter informações sobre uma lista específica.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O ID do site do SharePoint.
|
||||
- `list_id` (string, obrigatório): O ID da lista.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_list_items">
|
||||
**Descrição:** Obter itens de uma lista do SharePoint.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O ID do site do SharePoint.
|
||||
- `list_id` (string, obrigatório): O ID da lista.
|
||||
- `expand` (string, opcional): Expandir dados relacionados (ex: 'fields').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/create_list_item">
|
||||
**Descrição:** Criar um novo item em uma lista do SharePoint.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O ID do site do SharePoint.
|
||||
- `list_id` (string, obrigatório): O ID da lista.
|
||||
- `fields` (object, obrigatório): Os valores de campo para o novo item.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/update_list_item">
|
||||
**Descrição:** Atualizar um item em uma lista do SharePoint.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O ID do site do SharePoint.
|
||||
- `list_id` (string, obrigatório): O ID da lista.
|
||||
- `item_id` (string, obrigatório): O ID do item a atualizar.
|
||||
- `fields` (object, obrigatório): Os valores de campo a atualizar.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/delete_list_item">
|
||||
**Descrição:** Excluir um item de uma lista do SharePoint.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O ID do site do SharePoint.
|
||||
- `list_id` (string, obrigatório): O ID da lista.
|
||||
- `item_id` (string, obrigatório): O ID do item a excluir.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/upload_file_to_library">
|
||||
**Descrição:** Fazer upload de um arquivo para uma biblioteca de documentos do SharePoint.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O ID do site do SharePoint.
|
||||
- `file_path` (string, obrigatório): O caminho onde fazer upload do arquivo (ex: 'pasta/nomeDoArquivo.txt').
|
||||
- `content` (string, obrigatório): O conteúdo do arquivo a fazer upload.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/list_files">
|
||||
**Descrição:** Recuperar arquivos e pastas de uma biblioteca de documentos do SharePoint. Por padrão, lista a pasta raiz, mas você pode navegar em subpastas fornecendo um folder_id.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `folder_id` (string, opcional): O ID da pasta para listar o conteúdo. Use 'root' para a pasta raiz, ou forneça um ID de pasta de uma chamada anterior de list_files. Padrão: 'root'
|
||||
- `top` (integer, opcional): Número máximo de itens a retornar por página (1-1000). Padrão: 50
|
||||
- `skip_token` (string, opcional): Token de paginação de uma resposta anterior para buscar a próxima página de resultados.
|
||||
- `orderby` (string, opcional): Ordem de classificação dos resultados (ex: 'name asc', 'size desc', 'lastModifiedDateTime desc'). Padrão: 'name asc'
|
||||
- `filter` (string, opcional): Filtro OData para restringir resultados (ex: 'file ne null' apenas para arquivos, 'folder ne null' apenas para pastas).
|
||||
- `select` (string, opcional): Lista de campos separados por vírgula para retornar (ex: 'id,name,size,folder,file,webUrl,lastModifiedDateTime').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/delete_file">
|
||||
**Descrição:** Excluir um arquivo ou pasta de uma biblioteca de documentos do SharePoint. Para pastas, todo o conteúdo é excluído recursivamente. Os itens são movidos para a lixeira do site.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo ou pasta a excluir. Obtenha de list_files.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/list_files_by_path">
|
||||
**Descrição:** Listar arquivos e pastas em uma pasta de biblioteca de documentos do SharePoint pelo caminho. Mais eficiente do que múltiplas chamadas list_files para navegação profunda.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `folder_path` (string, obrigatório): O caminho completo para a pasta sem barras iniciais/finais (ex: 'Documents', 'Reports/2024/Q1').
|
||||
- `top` (integer, opcional): Número máximo de itens a retornar por página (1-1000). Padrão: 50
|
||||
- `skip_token` (string, opcional): Token de paginação de uma resposta anterior para buscar a próxima página de resultados.
|
||||
- `orderby` (string, opcional): Ordem de classificação dos resultados (ex: 'name asc', 'size desc'). Padrão: 'name asc'
|
||||
- `select` (string, opcional): Lista de campos separados por vírgula para retornar (ex: 'id,name,size,folder,file,webUrl,lastModifiedDateTime').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/download_file">
|
||||
**Descrição:** Baixar conteúdo bruto de um arquivo de uma biblioteca de documentos do SharePoint. Use apenas para arquivos de texto simples (.txt, .csv, .json). Para arquivos Excel, use as ações específicas de Excel. Para arquivos Word, use get_word_document_content.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo a baixar. Obtenha de list_files ou list_files_by_path.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_file_info">
|
||||
**Descrição:** Recuperar metadados detalhados de um arquivo ou pasta específico em uma biblioteca de documentos do SharePoint, incluindo nome, tamanho, datas de criação/modificação e informações do autor.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo ou pasta. Obtenha de list_files ou list_files_by_path.
|
||||
- `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'id,name,size,createdDateTime,lastModifiedDateTime,webUrl,createdBy,lastModifiedBy').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/create_folder">
|
||||
**Descrição:** Criar uma nova pasta em uma biblioteca de documentos do SharePoint. Por padrão, cria a pasta na raiz; use parent_id para criar subpastas.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `folder_name` (string, obrigatório): Nome para a nova pasta. Não pode conter: \ / : * ? " < > |
|
||||
- `parent_id` (string, opcional): O ID da pasta pai. Use 'root' para a raiz da biblioteca de documentos, ou forneça um ID de pasta de list_files. Padrão: 'root'
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/search_files">
|
||||
**Descrição:** Pesquisar arquivos e pastas em uma biblioteca de documentos do SharePoint por palavras-chave. Pesquisa nomes de arquivos, nomes de pastas e conteúdo de arquivos para documentos Office. Não use curingas ou caracteres especiais.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `query` (string, obrigatório): Palavras-chave de pesquisa (ex: 'relatório', 'orçamento 2024'). Curingas como *.txt não são suportados.
|
||||
- `top` (integer, opcional): Número máximo de resultados a retornar por página (1-1000). Padrão: 50
|
||||
- `skip_token` (string, opcional): Token de paginação de uma resposta anterior para buscar a próxima página de resultados.
|
||||
- `select` (string, opcional): Lista de campos separados por vírgula para retornar (ex: 'id,name,size,folder,file,webUrl,lastModifiedDateTime').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/copy_file">
|
||||
**Descrição:** Copiar um arquivo ou pasta para um novo local dentro do SharePoint. O item original permanece inalterado. A operação de cópia é assíncrona para arquivos grandes.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo ou pasta a copiar. Obtenha de list_files ou search_files.
|
||||
- `destination_folder_id` (string, obrigatório): O ID da pasta de destino. Use 'root' para a pasta raiz, ou um ID de pasta de list_files.
|
||||
- `new_name` (string, opcional): Novo nome para a cópia. Se não fornecido, o nome original é usado.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/move_file">
|
||||
**Descrição:** Mover um arquivo ou pasta para um novo local dentro do SharePoint. O item é removido de sua localização original. Para pastas, todo o conteúdo é movido também.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo ou pasta a mover. Obtenha de list_files ou search_files.
|
||||
- `destination_folder_id` (string, obrigatório): O ID da pasta de destino. Use 'root' para a pasta raiz, ou um ID de pasta de list_files.
|
||||
- `new_name` (string, opcional): Novo nome para o item movido. Se não fornecido, o nome original é mantido.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_worksheets">
|
||||
**Descrição:** Listar todas as planilhas (abas) em uma pasta de trabalho Excel armazenada em uma biblioteca de documentos do SharePoint. Use o nome da planilha retornado com outras ações de Excel.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'id,name,position,visibility').
|
||||
- `filter` (string, opcional): Expressão de filtro OData (ex: "visibility eq 'Visible'" para excluir planilhas ocultas).
|
||||
- `top` (integer, opcional): Número máximo de planilhas a retornar. Mínimo: 1, Máximo: 999
|
||||
- `orderby` (string, opcional): Ordem de classificação (ex: 'position asc' para retornar planilhas na ordem das abas).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/create_excel_worksheet">
|
||||
**Descrição:** Criar uma nova planilha (aba) em uma pasta de trabalho Excel armazenada em uma biblioteca de documentos do SharePoint. A nova planilha é adicionada no final da lista de abas.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `name` (string, obrigatório): Nome para a nova planilha. Máximo de 31 caracteres. Não pode conter: \ / * ? : [ ]. Deve ser único na pasta de trabalho.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_range_data">
|
||||
**Descrição:** Recuperar valores de células de um intervalo específico em uma planilha Excel armazenada no SharePoint. Para ler todos os dados sem saber as dimensões, use get_excel_used_range em vez disso.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha (aba) para leitura. Obtenha de get_excel_worksheets. Sensível a maiúsculas e minúsculas.
|
||||
- `range` (string, obrigatório): Intervalo de células em notação A1 (ex: 'A1:C10', 'A:C', '1:5', 'A1').
|
||||
- `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'address,values,formulas,numberFormat,text').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/update_excel_range_data">
|
||||
**Descrição:** Escrever valores em um intervalo específico em uma planilha Excel armazenada no SharePoint. Sobrescreve o conteúdo existente das células. As dimensões do array de valores devem corresponder exatamente às dimensões do intervalo.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha (aba) a atualizar. Obtenha de get_excel_worksheets. Sensível a maiúsculas e minúsculas.
|
||||
- `range` (string, obrigatório): Intervalo de células em notação A1 onde os valores serão escritos (ex: 'A1:C3' para um bloco 3x3).
|
||||
- `values` (array, obrigatório): Array 2D de valores (linhas contendo células). Exemplo para A1:B2: [["Cabeçalho1", "Cabeçalho2"], ["Valor1", "Valor2"]]. Use null para limpar uma célula.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_used_range_metadata">
|
||||
**Descrição:** Retornar apenas os metadados (endereço e dimensões) do intervalo utilizado em uma planilha, sem os valores reais das células. Ideal para arquivos grandes para entender o tamanho da planilha antes de ler dados em blocos.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha (aba) para leitura. Obtenha de get_excel_worksheets. Sensível a maiúsculas e minúsculas.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_used_range">
|
||||
**Descrição:** Recuperar todas as células contendo dados em uma planilha armazenada no SharePoint. Não use para arquivos maiores que 2MB. Para arquivos grandes, use get_excel_used_range_metadata primeiro, depois get_excel_range_data para ler em blocos menores.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha (aba) para leitura. Obtenha de get_excel_worksheets. Sensível a maiúsculas e minúsculas.
|
||||
- `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'address,values,formulas,numberFormat,text,rowCount,columnCount').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_cell">
|
||||
**Descrição:** Recuperar o valor de uma única célula por índice de linha e coluna de um arquivo Excel no SharePoint. Os índices são baseados em 0 (linha 0 = linha 1 do Excel, coluna 0 = coluna A).
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha (aba). Obtenha de get_excel_worksheets. Sensível a maiúsculas e minúsculas.
|
||||
- `row` (integer, obrigatório): Índice de linha baseado em 0 (linha 0 = linha 1 do Excel). Intervalo válido: 0-1048575
|
||||
- `column` (integer, obrigatório): Índice de coluna baseado em 0 (coluna 0 = A, coluna 1 = B). Intervalo válido: 0-16383
|
||||
- `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'address,values,formulas,numberFormat,text').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/add_excel_table">
|
||||
**Descrição:** Converter um intervalo de células em uma tabela Excel formatada com recursos de filtragem, classificação e dados estruturados. Tabelas habilitam add_excel_table_row para adicionar dados.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha contendo o intervalo de dados. Obtenha de get_excel_worksheets.
|
||||
- `range` (string, obrigatório): Intervalo de células para converter em tabela, incluindo cabeçalhos e dados (ex: 'A1:D10' onde A1:D1 contém cabeçalhos de coluna).
|
||||
- `has_headers` (boolean, opcional): Defina como true se a primeira linha contém cabeçalhos de coluna. Padrão: true
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_tables">
|
||||
**Descrição:** Listar todas as tabelas em uma planilha Excel específica armazenada no SharePoint. Retorna propriedades da tabela incluindo id, name, showHeaders e showTotals.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha para obter tabelas. Obtenha de get_excel_worksheets.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/add_excel_table_row">
|
||||
**Descrição:** Adicionar uma nova linha ao final de uma tabela Excel em um arquivo do SharePoint. O array de valores deve ter o mesmo número de elementos que o número de colunas da tabela.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha contendo a tabela. Obtenha de get_excel_worksheets.
|
||||
- `table_name` (string, obrigatório): Nome da tabela para adicionar a linha (ex: 'Table1'). Obtenha de get_excel_tables. Sensível a maiúsculas e minúsculas.
|
||||
- `values` (array, obrigatório): Array de valores de células para a nova linha, um por coluna na ordem da tabela (ex: ["João Silva", "joao@exemplo.com", 25]).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_table_data">
|
||||
**Descrição:** Obter todas as linhas de uma tabela Excel em um arquivo do SharePoint como um intervalo de dados. Mais fácil do que get_excel_range_data ao trabalhar com tabelas estruturadas, pois não é necessário saber o intervalo exato.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha contendo a tabela. Obtenha de get_excel_worksheets.
|
||||
- `table_name` (string, obrigatório): Nome da tabela para obter dados (ex: 'Table1'). Obtenha de get_excel_tables. Sensível a maiúsculas e minúsculas.
|
||||
- `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'address,values,formulas,numberFormat,text').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/create_excel_chart">
|
||||
**Descrição:** Criar uma visualização de gráfico em uma planilha Excel armazenada no SharePoint a partir de um intervalo de dados. O gráfico é incorporado na planilha.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha onde o gráfico será criado. Obtenha de get_excel_worksheets.
|
||||
- `chart_type` (string, obrigatório): Tipo de gráfico (ex: 'ColumnClustered', 'ColumnStacked', 'Line', 'LineMarkers', 'Pie', 'Bar', 'BarClustered', 'Area', 'Scatter', 'Doughnut').
|
||||
- `source_data` (string, obrigatório): Intervalo de dados para o gráfico em notação A1, incluindo cabeçalhos (ex: 'A1:B10').
|
||||
- `series_by` (string, opcional): Como as séries de dados são organizadas: 'Auto', 'Columns' ou 'Rows'. Padrão: 'Auto'
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/list_excel_charts">
|
||||
**Descrição:** Listar todos os gráficos incorporados em uma planilha Excel armazenada no SharePoint. Retorna propriedades do gráfico incluindo id, name, chartType, height, width e position.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha para listar gráficos. Obtenha de get_excel_worksheets.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/delete_excel_worksheet">
|
||||
**Descrição:** Remover permanentemente uma planilha (aba) e todo seu conteúdo de uma pasta de trabalho Excel armazenada no SharePoint. Não pode ser desfeito. Uma pasta de trabalho deve ter pelo menos uma planilha.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha a excluir. Sensível a maiúsculas e minúsculas. Todos os dados, tabelas e gráficos nesta planilha serão permanentemente removidos.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/delete_excel_table">
|
||||
**Descrição:** Remover uma tabela de uma planilha Excel no SharePoint. Isto exclui a estrutura da tabela (filtragem, formatação, recursos de tabela) mas preserva os dados subjacentes das células.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
- `worksheet_name` (string, obrigatório): Nome da planilha contendo a tabela. Obtenha de get_excel_worksheets.
|
||||
- `table_name` (string, obrigatório): Nome da tabela a excluir (ex: 'Table1'). Obtenha de get_excel_tables. Os dados nas células permanecerão após a exclusão da tabela.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/list_excel_names">
|
||||
**Descrição:** Recuperar todos os intervalos nomeados definidos em uma pasta de trabalho Excel armazenada no SharePoint. Intervalos nomeados são rótulos definidos pelo usuário para intervalos de células (ex: 'DadosVendas' para A1:D100).
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_word_document_content">
|
||||
**Descrição:** Baixar e extrair conteúdo de texto de um documento Word (.docx) armazenado em uma biblioteca de documentos do SharePoint. Esta é a maneira recomendada de ler documentos Word do SharePoint.
|
||||
|
||||
**Parâmetros:**
|
||||
- `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites.
|
||||
- `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos.
|
||||
- `item_id` (string, obrigatório): O identificador único do documento Word (.docx) no SharePoint. Obtenha de list_files ou search_files.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Exemplos de Uso
|
||||
|
||||
### Configuração Básica do Agente Microsoft SharePoint
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente com capacidades do Microsoft SharePoint
|
||||
sharepoint_agent = Agent(
|
||||
role="Gerenciador SharePoint",
|
||||
goal="Gerenciar sites, listas e documentos do SharePoint de forma eficiente",
|
||||
backstory="Um assistente IA especializado em administração do Microsoft SharePoint e gerenciamento de conteúdo.",
|
||||
apps=['microsoft_sharepoint'] # Todas as ações do SharePoint estarão disponíveis
|
||||
)
|
||||
|
||||
# Tarefa para obter todos os sites
|
||||
get_sites_task = Task(
|
||||
description="Listar todos os sites do SharePoint aos quais tenho acesso.",
|
||||
agent=sharepoint_agent,
|
||||
expected_output="Uma lista de sites do SharePoint com seus nomes de exibição e URLs."
|
||||
)
|
||||
|
||||
# Execute a tarefa
|
||||
crew = Crew(
|
||||
agents=[sharepoint_agent],
|
||||
tasks=[get_sites_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Problemas Comuns
|
||||
|
||||
**Erros de Autenticação**
|
||||
|
||||
- Certifique-se de que sua conta Microsoft tenha as permissões necessárias para acesso ao SharePoint (ex: `Sites.Read.All`, `Sites.ReadWrite.All`).
|
||||
- Verifique se a conexão OAuth inclui todos os escopos necessários.
|
||||
|
||||
**Problemas de ID de Site/Lista/Item**
|
||||
|
||||
- Verifique novamente os IDs de site, lista e item para correção.
|
||||
- Certifique-se de que os recursos referenciados existem e estão acessíveis.
|
||||
|
||||
### 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 com configuração
|
||||
ou solução de problemas da integração Microsoft SharePoint.
|
||||
</Card>
|
||||
242
docs/edge/pt-BR/enterprise/integrations/microsoft_teams.mdx
Normal file
242
docs/edge/pt-BR/enterprise/integrations/microsoft_teams.mdx
Normal file
@@ -0,0 +1,242 @@
|
||||
---
|
||||
title: Integração Microsoft Teams
|
||||
description: "Colaboração em equipe e comunicação com integração Microsoft Teams para CrewAI."
|
||||
icon: "users"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Permita que seus agentes acessem dados do Teams, enviem mensagens, criem reuniões e gerenciem canais. Automatize a comunicação da equipe, agende reuniões, recupere mensagens e simplifique seus fluxos de trabalho de colaboração com automação alimentada por IA.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
Antes de usar a integração Microsoft Teams, certifique-se de ter:
|
||||
|
||||
- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa
|
||||
- Uma conta Microsoft com acesso ao Teams
|
||||
- Conectado sua conta Microsoft através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
|
||||
|
||||
## Configurando a Integração Microsoft Teams
|
||||
|
||||
### 1. Conecte sua Conta Microsoft
|
||||
|
||||
1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors)
|
||||
2. Encontre **Microsoft Teams** 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 Teams
|
||||
5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## Ações Disponíveis
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="microsoft_teams/get_teams">
|
||||
**Descrição:** Obter todas as equipes das quais o usuário é membro.
|
||||
|
||||
**Parâmetros:**
|
||||
- Nenhum parâmetro necessário.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/get_channels">
|
||||
**Descrição:** Obter canais em uma equipe específica.
|
||||
|
||||
**Parâmetros:**
|
||||
- `team_id` (string, obrigatório): O ID da equipe.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/send_message">
|
||||
**Descrição:** Enviar uma mensagem para um canal do Teams.
|
||||
|
||||
**Parâmetros:**
|
||||
- `team_id` (string, obrigatório): O ID da equipe.
|
||||
- `channel_id` (string, obrigatório): O ID do canal.
|
||||
- `message` (string, obrigatório): O conteúdo da mensagem.
|
||||
- `content_type` (string, opcional): Tipo de conteúdo (html ou text). Opções: html, text. Padrão: text.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/get_messages">
|
||||
**Descrição:** Obter mensagens de um canal do Teams.
|
||||
|
||||
**Parâmetros:**
|
||||
- `team_id` (string, obrigatório): O ID da equipe.
|
||||
- `channel_id` (string, obrigatório): O ID do canal.
|
||||
- `top` (integer, opcional): Número de mensagens a recuperar (máx 50). Padrão: 20.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/create_meeting">
|
||||
**Descrição:** Criar uma reunião do Teams.
|
||||
|
||||
**Parâmetros:**
|
||||
- `subject` (string, obrigatório): Assunto/título da reunião.
|
||||
- `startDateTime` (string, obrigatório): Hora de início da reunião (formato ISO 8601 com fuso horário).
|
||||
- `endDateTime` (string, obrigatório): Hora de término da reunião (formato ISO 8601 com fuso horário).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/search_online_meetings_by_join_url">
|
||||
**Descrição:** Pesquisar reuniões online por URL de participação na web.
|
||||
|
||||
**Parâmetros:**
|
||||
- `join_web_url` (string, obrigatório): A URL de participação na web da reunião a pesquisar.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/search_online_meetings_by_meeting_id">
|
||||
**Descrição:** Pesquisar reuniões online por ID externo da reunião.
|
||||
|
||||
**Parâmetros:**
|
||||
- `join_meeting_id` (string, obrigatório): O ID da reunião (código numérico) que os participantes usam para entrar. É o joinMeetingId exibido nos convites da reunião, não o meeting id da API Graph.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/get_meeting">
|
||||
**Descrição:** Obter detalhes de uma reunião online específica.
|
||||
|
||||
**Parâmetros:**
|
||||
- `meeting_id` (string, obrigatório): O ID da reunião na API Graph (string alfanumérica longa). Obter pelas ações create_meeting ou search_online_meetings. Diferente do joinMeetingId numérico.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/get_team_members">
|
||||
**Descrição:** Obter membros de uma equipe específica.
|
||||
|
||||
**Parâmetros:**
|
||||
- `team_id` (string, obrigatório): O identificador único da equipe. Obter pela ação get_teams.
|
||||
- `top` (integer, opcional): Número máximo de membros a recuperar por página (1-999). Padrão: 100.
|
||||
- `skip_token` (string, opcional): Token de paginação de uma resposta anterior. Quando a resposta incluir @odata.nextLink, extraia o valor do parâmetro $skiptoken e passe aqui para obter a próxima página de resultados.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/create_channel">
|
||||
**Descrição:** Criar um novo canal em uma equipe.
|
||||
|
||||
**Parâmetros:**
|
||||
- `team_id` (string, obrigatório): O identificador único da equipe. Obter pela ação get_teams.
|
||||
- `display_name` (string, obrigatório): Nome do canal exibido no Teams. Deve ser único na equipe. Máx 50 caracteres.
|
||||
- `description` (string, opcional): Descrição opcional explicando o propósito do canal. Visível nos detalhes do canal. Máx 1024 caracteres.
|
||||
- `membership_type` (string, opcional): Visibilidade do canal. Opções: standard, private. "standard" = visível para todos os membros da equipe, "private" = visível apenas para membros adicionados especificamente. Padrão: standard.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/get_message_replies">
|
||||
**Descrição:** Obter respostas a uma mensagem específica em um canal.
|
||||
|
||||
**Parâmetros:**
|
||||
- `team_id` (string, obrigatório): O identificador único da equipe. Obter pela ação get_teams.
|
||||
- `channel_id` (string, obrigatório): O identificador único do canal. Obter pela ação get_channels.
|
||||
- `message_id` (string, obrigatório): O identificador único da mensagem pai. Obter pela ação get_messages.
|
||||
- `top` (integer, opcional): Número máximo de respostas a recuperar por página (1-50). Padrão: 50.
|
||||
- `skip_token` (string, opcional): Token de paginação de uma resposta anterior. Quando a resposta incluir @odata.nextLink, extraia o valor do parâmetro $skiptoken e passe aqui para obter a próxima página de resultados.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/reply_to_message">
|
||||
**Descrição:** Responder a uma mensagem em um canal do Teams.
|
||||
|
||||
**Parâmetros:**
|
||||
- `team_id` (string, obrigatório): O identificador único da equipe. Obter pela ação get_teams.
|
||||
- `channel_id` (string, obrigatório): O identificador único do canal. Obter pela ação get_channels.
|
||||
- `message_id` (string, obrigatório): O identificador único da mensagem a responder. Obter pela ação get_messages.
|
||||
- `message` (string, obrigatório): O conteúdo da resposta. Para HTML, inclua tags de formatação. Para texto, use apenas texto simples.
|
||||
- `content_type` (string, opcional): Formato do conteúdo. Opções: html, text. "text" para texto simples, "html" para texto rico com formatação. Padrão: text.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/update_meeting">
|
||||
**Descrição:** Atualizar uma reunião online existente.
|
||||
|
||||
**Parâmetros:**
|
||||
- `meeting_id` (string, obrigatório): O identificador único da reunião. Obter pelas ações create_meeting ou search_online_meetings.
|
||||
- `subject` (string, opcional): Novo título da reunião.
|
||||
- `startDateTime` (string, opcional): Nova hora de início no formato ISO 8601 com fuso horário. Exemplo: "2024-01-20T10:00:00-08:00".
|
||||
- `endDateTime` (string, opcional): Nova hora de término no formato ISO 8601 com fuso horário.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/delete_meeting">
|
||||
**Descrição:** Excluir uma reunião online.
|
||||
|
||||
**Parâmetros:**
|
||||
- `meeting_id` (string, obrigatório): O identificador único da reunião a excluir. Obter pelas ações create_meeting ou search_online_meetings.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Exemplos de Uso
|
||||
|
||||
### Configuração Básica do Agente Microsoft Teams
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente com capacidades do Microsoft Teams
|
||||
teams_agent = Agent(
|
||||
role="Coordenador do Teams",
|
||||
goal="Gerenciar comunicação e reuniões do Teams de forma eficiente",
|
||||
backstory="Um assistente IA especializado em operações do Microsoft Teams e colaboração em equipe.",
|
||||
apps=['microsoft_teams'] # Todas as ações do Teams estarão disponíveis
|
||||
)
|
||||
|
||||
# Tarefa para listar equipes e canais
|
||||
explore_teams_task = Task(
|
||||
description="Listar todas as equipes das quais sou membro e depois obter os canais da primeira equipe.",
|
||||
agent=teams_agent,
|
||||
expected_output="Lista de equipes e canais exibida."
|
||||
)
|
||||
|
||||
# Execute a tarefa
|
||||
crew = Crew(
|
||||
agents=[teams_agent],
|
||||
tasks=[explore_teams_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Problemas Comuns
|
||||
|
||||
**Erros de Autenticação**
|
||||
|
||||
- Certifique-se de que sua conta Microsoft tenha as permissões necessárias para acesso ao Teams.
|
||||
- Escopos necessários incluem: `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Send`, `ChannelMessage.Read.All`, `OnlineMeetings.ReadWrite`, `OnlineMeetings.Read`.
|
||||
|
||||
**Acesso a Equipes e Canais**
|
||||
|
||||
- Certifique-se de que você é membro das equipes que está tentando acessar.
|
||||
- Verifique novamente os IDs de equipe e canal para correção.
|
||||
|
||||
### 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 com configuração
|
||||
ou solução de problemas da integração Microsoft Teams.
|
||||
</Card>
|
||||
172
docs/edge/pt-BR/enterprise/integrations/microsoft_word.mdx
Normal file
172
docs/edge/pt-BR/enterprise/integrations/microsoft_word.mdx
Normal file
@@ -0,0 +1,172 @@
|
||||
---
|
||||
title: Integração Microsoft Word
|
||||
description: "Criação e gerenciamento de documentos com integração Microsoft Word para CrewAI."
|
||||
icon: "file-word"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Permita que seus agentes criem, leiam e gerenciem documentos do Word e arquivos de texto no OneDrive ou SharePoint. Automatize a criação de documentos, recupere conteúdo, gerencie propriedades de documentos e simplifique seus fluxos de trabalho de documentos com automação alimentada por IA.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
Antes de usar a integração Microsoft Word, certifique-se de ter:
|
||||
|
||||
- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa
|
||||
- Uma conta Microsoft com acesso ao Word e OneDrive/SharePoint
|
||||
- Conectado sua conta Microsoft através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors)
|
||||
|
||||
## Configurando a Integração Microsoft Word
|
||||
|
||||
### 1. Conecte sua Conta Microsoft
|
||||
|
||||
1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors)
|
||||
2. Encontre **Microsoft Word** 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 a arquivos
|
||||
5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## Ações Disponíveis
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="microsoft_word/get_documents">
|
||||
**Descrição:** Obter todos os documentos do Word do OneDrive ou SharePoint.
|
||||
|
||||
**Parâmetros:**
|
||||
- `select` (string, opcional): Selecionar propriedades específicas para retornar.
|
||||
- `filter` (string, opcional): Filtrar resultados usando sintaxe OData.
|
||||
- `expand` (string, opcional): Expandir recursos relacionados inline.
|
||||
- `top` (integer, opcional): Número de itens a retornar (mín 1, máx 999).
|
||||
- `orderby` (string, opcional): Ordenar resultados por propriedades especificadas.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_word/create_text_document">
|
||||
**Descrição:** Criar um documento de texto (.txt) com conteúdo. RECOMENDADO para criação de conteúdo programático que precisa ser legível e editável.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_name` (string, obrigatório): Nome do documento de texto (deve terminar com .txt).
|
||||
- `content` (string, opcional): Conteúdo de texto para o documento. Padrão: "Este é um novo documento de texto criado via API."
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_word/get_document_content">
|
||||
**Descrição:** Obter o conteúdo de um documento (funciona melhor com arquivos de texto).
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do documento.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_word/get_document_properties">
|
||||
**Descrição:** Obter propriedades e metadados de um documento.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do documento.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_word/delete_document">
|
||||
**Descrição:** Excluir um documento.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do documento a excluir.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_word/copy_document">
|
||||
**Descrição:** Copiar um documento para um novo local no OneDrive.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do documento a copiar.
|
||||
- `name` (string, opcional): Novo nome para o documento copiado.
|
||||
- `parent_id` (string, opcional): O ID da pasta de destino (padrão: raiz).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_word/move_document">
|
||||
**Descrição:** Mover um documento para um novo local no OneDrive.
|
||||
|
||||
**Parâmetros:**
|
||||
- `file_id` (string, obrigatório): O ID do documento a mover.
|
||||
- `parent_id` (string, obrigatório): O ID da pasta de destino.
|
||||
- `name` (string, opcional): Novo nome para o documento movido.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Exemplos de Uso
|
||||
|
||||
### Configuração Básica do Agente Microsoft Word
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Crie um agente com capacidades do Microsoft Word
|
||||
word_agent = Agent(
|
||||
role="Gerenciador de Documentos",
|
||||
goal="Gerenciar documentos do Word e arquivos de texto de forma eficiente",
|
||||
backstory="Um assistente IA especializado em operações de documentos do Microsoft Word e gerenciamento de conteúdo.",
|
||||
apps=['microsoft_word'] # Todas as ações do Word estarão disponíveis
|
||||
)
|
||||
|
||||
# Tarefa para criar um novo documento de texto
|
||||
create_doc_task = Task(
|
||||
description="Criar um novo documento de texto chamado 'notas_reuniao.txt' com conteúdo 'Notas da Reunião de Janeiro de 2024: Pontos-chave de discussão e itens de ação.'",
|
||||
agent=word_agent,
|
||||
expected_output="Novo documento de texto 'notas_reuniao.txt' criado com sucesso."
|
||||
)
|
||||
|
||||
# Execute a tarefa
|
||||
crew = Crew(
|
||||
agents=[word_agent],
|
||||
tasks=[create_doc_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## Solução de Problemas
|
||||
|
||||
### Problemas Comuns
|
||||
|
||||
**Erros de Autenticação**
|
||||
|
||||
- Certifique-se de que sua conta Microsoft tenha as permissões necessárias para acesso a arquivos (ex: `Files.Read.All`, `Files.ReadWrite.All`).
|
||||
- Verifique se a conexão OAuth inclui todos os escopos necessários.
|
||||
|
||||
**Problemas de Criação de Arquivos**
|
||||
|
||||
- Ao criar documentos de texto, certifique-se de que o `file_name` termine com extensão `.txt`.
|
||||
- Verifique se você tem permissões de escrita no local de destino (OneDrive/SharePoint).
|
||||
|
||||
### 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 com configuração
|
||||
ou solução de problemas da integração Microsoft Word.
|
||||
</Card>
|
||||
517
docs/edge/pt-BR/enterprise/integrations/notion.mdx
Normal file
517
docs/edge/pt-BR/enterprise/integrations/notion.mdx
Normal file
@@ -0,0 +1,517 @@
|
||||
---
|
||||
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"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 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 AMP](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 AMP](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 de Integração](https://app.crewai.com/crewai_plus/settings/integrations)
|
||||
|
||||
### 2. Instale o Pacote Necessário
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. Configuração de variável de ambiente
|
||||
|
||||
<Note>
|
||||
Para usar integrações com `Agent(apps=[])`, você deve definir a variável de
|
||||
ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token"
|
||||
```
|
||||
|
||||
Ou adicione ao seu arquivo `.env`:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
# 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.",
|
||||
apps=['notion']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
content_manager = Agent(
|
||||
role="Content Manager",
|
||||
goal="Create and manage content pages efficiently",
|
||||
backstory="An AI assistant that focuses on content creation and management.",
|
||||
apps=['notion']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['notion']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
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.",
|
||||
apps=['notion']
|
||||
)
|
||||
|
||||
# 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
|
||||
|
||||
doc_automator = Agent(
|
||||
role="Documentation Automator",
|
||||
goal="Automate documentation workflows and maintenance",
|
||||
backstory="An AI assistant that automates repetitive documentation tasks.",
|
||||
apps=['notion']
|
||||
)
|
||||
|
||||
# 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>
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user