diff --git a/docs/docs.json b/docs/docs.json index 1f949e35e..2823d97cb 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -7,7 +7,7 @@ "light": "#F3A78B", "dark": "#C94C3C" }, - "favicon": "images/favicon.svg", + "favicon": "/images/favicon.svg", "contextual": { "options": [ "copy", @@ -17,369 +17,736 @@ ] }, "navigation": { - "tabs": [ + "languages": [ { - "tab": "Documentation", - "groups": [ + "language": "en", + "global": { + "anchors": [ + { + "anchor": "Website", + "href": "https://crewai.com", + "icon": "globe" + }, + { + "anchor": "Forum", + "href": "https://community.crewai.com", + "icon": "discourse" + }, + { + "anchor": "Crew GPT", + "href": "https://chatgpt.com/g/g-qqTuUWsBY-crewai-assistant", + "icon": "robot" + }, + { + "anchor": "Get Help", + "href": "mailto:support@crewai.com", + "icon": "headset" + } + ] + }, + "tabs": [ { - "group": "Get Started", - "pages": [ - "introduction", - "installation", - "quickstart" - ] - }, - { - "group": "Guides", - "pages": [ + "tab": "Documentation", + "groups": [ { - "group": "Strategy", + "group": "Get Started", "pages": [ - "guides/concepts/evaluating-use-cases" + "en/introduction", + "en/installation", + "en/quickstart" ] }, { - "group": "Agents", + "group": "Guides", "pages": [ - "guides/agents/crafting-effective-agents" + { + "group": "Strategy", + "pages": [ + "en/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "Agents", + "pages": [ + "en/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "Crews", + "pages": [ + "en/guides/crews/first-crew" + ] + }, + { + "group": "Flows", + "pages": [ + "en/guides/flows/first-flow", + "en/guides/flows/mastering-flow-state" + ] + }, + { + "group": "Advanced", + "pages": [ + "en/guides/advanced/customizing-prompts", + "en/guides/advanced/fingerprinting" + ] + } ] }, { - "group": "Crews", + "group": "Core Concepts", "pages": [ - "guides/crews/first-crew" + "en/concepts/agents", + "en/concepts/tasks", + "en/concepts/crews", + "en/concepts/flows", + "en/concepts/knowledge", + "en/concepts/llms", + "en/concepts/processes", + "en/concepts/collaboration", + "en/concepts/training", + "en/concepts/memory", + "en/concepts/reasoning", + "en/concepts/planning", + "en/concepts/testing", + "en/concepts/cli", + "en/concepts/tools", + "en/concepts/event-listener" ] }, { - "group": "Flows", + "group": "MCP Integration", "pages": [ - "guides/flows/first-flow", - "guides/flows/mastering-flow-state" + "en/mcp/overview", + "en/mcp/stdio", + "en/mcp/sse", + "en/mcp/streamable-http", + "en/mcp/multiple-servers", + "en/mcp/security" ] }, { - "group": "Advanced", + "group": "Tools", "pages": [ - "guides/advanced/customizing-prompts", - "guides/advanced/fingerprinting" + "en/tools/overview", + { + "group": "File & Document", + "pages": [ + "en/tools/file-document/overview", + "en/tools/file-document/filereadtool", + "en/tools/file-document/filewritetool", + "en/tools/file-document/pdfsearchtool", + "en/tools/file-document/docxsearchtool", + "en/tools/file-document/mdxsearchtool", + "en/tools/file-document/xmlsearchtool", + "en/tools/file-document/txtsearchtool", + "en/tools/file-document/jsonsearchtool", + "en/tools/file-document/csvsearchtool", + "en/tools/file-document/directorysearchtool", + "en/tools/file-document/directoryreadtool" + ] + }, + { + "group": "Web Scraping & Browsing", + "pages": [ + "en/tools/web-scraping/overview", + "en/tools/web-scraping/scrapewebsitetool", + "en/tools/web-scraping/scrapeelementfromwebsitetool", + "en/tools/web-scraping/scrapflyscrapetool", + "en/tools/web-scraping/seleniumscrapingtool", + "en/tools/web-scraping/scrapegraphscrapetool", + "en/tools/web-scraping/spidertool", + "en/tools/web-scraping/browserbaseloadtool", + "en/tools/web-scraping/hyperbrowserloadtool", + "en/tools/web-scraping/stagehandtool", + "en/tools/web-scraping/firecrawlcrawlwebsitetool", + "en/tools/web-scraping/firecrawlscrapewebsitetool", + "en/tools/web-scraping/oxylabsscraperstool" + ] + }, + { + "group": "Search & Research", + "pages": [ + "en/tools/search-research/overview", + "en/tools/search-research/serperdevtool", + "en/tools/search-research/bravesearchtool", + "en/tools/search-research/exasearchtool", + "en/tools/search-research/linkupsearchtool", + "en/tools/search-research/githubsearchtool", + "en/tools/search-research/websitesearchtool", + "en/tools/search-research/codedocssearchtool", + "en/tools/search-research/youtubechannelsearchtool", + "en/tools/search-research/youtubevideosearchtool" + ] + }, + { + "group": "Database & Data", + "pages": [ + "en/tools/database-data/overview", + "en/tools/database-data/mysqltool", + "en/tools/database-data/pgsearchtool", + "en/tools/database-data/snowflakesearchtool", + "en/tools/database-data/nl2sqltool", + "en/tools/database-data/qdrantvectorsearchtool", + "en/tools/database-data/weaviatevectorsearchtool" + ] + }, + { + "group": "AI & Machine Learning", + "pages": [ + "en/tools/ai-ml/overview", + "en/tools/ai-ml/dalletool", + "en/tools/ai-ml/visiontool", + "en/tools/ai-ml/aimindtool", + "en/tools/ai-ml/llamaindextool", + "en/tools/ai-ml/langchaintool", + "en/tools/ai-ml/ragtool", + "en/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "Cloud & Storage", + "pages": [ + "en/tools/cloud-storage/overview", + "en/tools/cloud-storage/s3readertool", + "en/tools/cloud-storage/s3writertool", + "en/tools/cloud-storage/bedrockinvokeagenttool", + "en/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Automation & Integration", + "pages": [ + "en/tools/automation/overview", + "en/tools/automation/apifyactorstool", + "en/tools/automation/composiotool", + "en/tools/automation/multiontool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "en/observability/overview", + "en/observability/agentops", + "en/observability/arize-phoenix", + "en/observability/langfuse", + "en/observability/langtrace", + "en/observability/maxim", + "en/observability/mlflow", + "en/observability/openlit", + "en/observability/opik", + "en/observability/patronus-evaluation", + "en/observability/portkey", + "en/observability/weave" + ] + }, + { + "group": "Learn", + "pages": [ + "en/learn/overview", + "en/learn/llm-selection-guide", + "en/learn/conditional-tasks", + "en/learn/coding-agents", + "en/learn/create-custom-tools", + "en/learn/custom-llm", + "en/learn/custom-manager-agent", + "en/learn/customizing-agents", + "en/learn/dalle-image-generation", + "en/learn/force-tool-output-as-result", + "en/learn/hierarchical-process", + "en/learn/human-input-on-execution", + "en/learn/kickoff-async", + "en/learn/kickoff-for-each", + "en/learn/llm-connections", + "en/learn/multimodal-agents", + "en/learn/replay-tasks-from-latest-crew-kickoff", + "en/learn/sequential-process", + "en/learn/using-annotations" + ] + }, + { + "group": "Telemetry", + "pages": [ + "en/telemetry" ] } ] }, { - "group": "Core Concepts", - "pages": [ - "concepts/agents", - "concepts/tasks", - "concepts/crews", - "concepts/flows", - "concepts/knowledge", - "concepts/llms", - "concepts/processes", - "concepts/collaboration", - "concepts/training", - "concepts/memory", - "concepts/reasoning", - "concepts/planning", - "concepts/testing", - "concepts/cli", - "concepts/tools", - "concepts/event-listener" - ] - }, - { - "group": "MCP Integration", - "pages": [ - "mcp/overview", - "mcp/stdio", - "mcp/sse", - "mcp/streamable-http", - "mcp/multiple-servers", - "mcp/security" - ] - }, - { - "group": "Tools", - "pages": [ - "tools/overview", + "tab": "Enterprise", + "groups": [ { - "group": "File & Document", + "group": "Getting Started", "pages": [ - "tools/file-document/overview", - "tools/file-document/filereadtool", - "tools/file-document/filewritetool", - "tools/file-document/pdfsearchtool", - "tools/file-document/docxsearchtool", - "tools/file-document/mdxsearchtool", - "tools/file-document/xmlsearchtool", - "tools/file-document/txtsearchtool", - "tools/file-document/jsonsearchtool", - "tools/file-document/csvsearchtool", - "tools/file-document/directorysearchtool", - "tools/file-document/directoryreadtool" + "en/enterprise/introduction" ] }, { - "group": "Web Scraping & Browsing", + "group": "Features", "pages": [ - "tools/web-scraping/overview", - "tools/web-scraping/scrapewebsitetool", - "tools/web-scraping/scrapeelementfromwebsitetool", - "tools/web-scraping/scrapflyscrapetool", - "tools/web-scraping/seleniumscrapingtool", - "tools/web-scraping/scrapegraphscrapetool", - "tools/web-scraping/spidertool", - "tools/web-scraping/browserbaseloadtool", - "tools/web-scraping/hyperbrowserloadtool", - "tools/web-scraping/stagehandtool", - "tools/web-scraping/firecrawlcrawlwebsitetool", - "tools/web-scraping/firecrawlscrapewebsitetool", - "tools/web-scraping/oxylabsscraperstool" + "en/enterprise/features/tool-repository", + "en/enterprise/features/webhook-streaming", + "en/enterprise/features/traces", + "en/enterprise/features/hallucination-guardrail", + "en/enterprise/features/integrations" ] }, { - "group": "Search & Research", + "group": "Integration Docs", "pages": [ - "tools/search-research/overview", - "tools/search-research/serperdevtool", - "tools/search-research/bravesearchtool", - "tools/search-research/exasearchtool", - "tools/search-research/linkupsearchtool", - "tools/search-research/githubsearchtool", - "tools/search-research/websitesearchtool", - "tools/search-research/codedocssearchtool", - "tools/search-research/youtubechannelsearchtool", - "tools/search-research/youtubevideosearchtool" + "en/enterprise/integrations/asana", + "en/enterprise/integrations/box", + "en/enterprise/integrations/clickup", + "en/enterprise/integrations/github", + "en/enterprise/integrations/gmail", + "en/enterprise/integrations/google_calendar", + "en/enterprise/integrations/google_sheets", + "en/enterprise/integrations/hubspot", + "en/enterprise/integrations/jira", + "en/enterprise/integrations/linear", + "en/enterprise/integrations/notion", + "en/enterprise/integrations/salesforce", + "en/enterprise/integrations/shopify", + "en/enterprise/integrations/slack", + "en/enterprise/integrations/stripe", + "en/enterprise/integrations/zendesk" ] }, { - "group": "Database & Data", + "group": "How-To Guides", "pages": [ - "tools/database-data/overview", - "tools/database-data/mysqltool", - "tools/database-data/pgsearchtool", - "tools/database-data/snowflakesearchtool", - "tools/database-data/nl2sqltool", - "tools/database-data/qdrantvectorsearchtool", - "tools/database-data/weaviatevectorsearchtool" + "en/enterprise/guides/build-crew", + "en/enterprise/guides/deploy-crew", + "en/enterprise/guides/kickoff-crew", + "en/enterprise/guides/update-crew", + "en/enterprise/guides/enable-crew-studio", + "en/enterprise/guides/azure-openai-setup", + "en/enterprise/guides/hubspot-trigger", + "en/enterprise/guides/react-component-export", + "en/enterprise/guides/salesforce-trigger", + "en/enterprise/guides/slack-trigger", + "en/enterprise/guides/team-management", + "en/enterprise/guides/webhook-automation", + "en/enterprise/guides/human-in-the-loop", + "en/enterprise/guides/zapier-trigger" ] }, { - "group": "AI & Machine Learning", + "group": "Resources", "pages": [ - "tools/ai-ml/overview", - "tools/ai-ml/dalletool", - "tools/ai-ml/visiontool", - "tools/ai-ml/aimindtool", - "tools/ai-ml/llamaindextool", - "tools/ai-ml/langchaintool", - "tools/ai-ml/ragtool", - "tools/ai-ml/codeinterpretertool" - ] - }, - { - "group": "Cloud & Storage", - "pages": [ - "tools/cloud-storage/overview", - "tools/cloud-storage/s3readertool", - "tools/cloud-storage/s3writertool", - "tools/cloud-storage/bedrockinvokeagenttool", - "tools/cloud-storage/bedrockkbretriever" - ] - }, - { - "group": "Automation & Integration", - "pages": [ - "tools/automation/overview", - "tools/automation/apifyactorstool", - "tools/automation/composiotool", - "tools/automation/multiontool" + "en/enterprise/resources/frequently-asked-questions" ] } ] }, { - "group": "Observability", - "pages": [ - "observability/overview", - "observability/agentops", - "observability/arize-phoenix", - "observability/langfuse", - "observability/langtrace", - "observability/maxim", - "observability/mlflow", - "observability/openlit", - "observability/opik", - "observability/patronus-evaluation", - "observability/portkey", - "observability/weave" + "tab": "API Reference", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "en/api-reference/introduction" + ] + }, + { + "group": "Endpoints", + "openapi": "enterprise-api.yaml" + } ] }, { - "group": "Learn", - "pages": [ - "learn/overview", - "learn/llm-selection-guide", - "learn/conditional-tasks", - "learn/coding-agents", - "learn/create-custom-tools", - "learn/custom-llm", - "learn/custom-manager-agent", - "learn/customizing-agents", - "learn/dalle-image-generation", - "learn/force-tool-output-as-result", - "learn/hierarchical-process", - "learn/human-input-on-execution", - "learn/kickoff-async", - "learn/kickoff-for-each", - "learn/llm-connections", - "learn/multimodal-agents", - "learn/replay-tasks-from-latest-crew-kickoff", - "learn/sequential-process", - "learn/using-annotations" + "tab": "Examples", + "groups": [ + { + "group": "Examples", + "pages": [ + "en/examples/example" + ] + } ] }, { - "group": "Telemetry", - "pages": [ - "telemetry" + "tab": "Releases", + "groups": [ + { + "group": "Releases", + "pages": [ + "en/changelog" + ] + } ] } ] }, { - "tab": "Enterprise", - "groups": [ + "language": "pt-BR", + "global": { + "anchors": [ + { + "anchor": "Website", + "href": "https://crewai.com", + "icon": "globe" + }, + { + "anchor": "Fórum", + "href": "https://community.crewai.com", + "icon": "discourse" + }, + { + "anchor": "Crew GPT", + "href": "https://chatgpt.com/g/g-qqTuUWsBY-crewai-assistant", + "icon": "robot" + }, + { + "anchor": "Obter Ajuda", + "href": "mailto:support@crewai.com", + "icon": "headset" + } + ] + }, + "tabs": [ { - "group": "Getting Started", - "pages": [ - "enterprise/introduction" + "tab": "Documentação", + "groups": [ + { + "group": "Começando", + "pages": [ + "pt-BR/introduction", + "pt-BR/installation", + "pt-BR/quickstart" + ] + }, + { + "group": "Guias", + "pages": [ + { + "group": "Estratégia", + "pages": [ + "pt-BR/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "Agentes", + "pages": [ + "pt-BR/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "Crews", + "pages": [ + "pt-BR/guides/crews/first-crew" + ] + }, + { + "group": "Flows", + "pages": [ + "pt-BR/guides/flows/first-flow", + "pt-BR/guides/flows/mastering-flow-state" + ] + }, + { + "group": "Avançado", + "pages": [ + "pt-BR/guides/advanced/customizing-prompts", + "pt-BR/guides/advanced/fingerprinting" + ] + } + ] + }, + { + "group": "Conceitos-Chave", + "pages": [ + "pt-BR/concepts/agents", + "pt-BR/concepts/tasks", + "pt-BR/concepts/crews", + "pt-BR/concepts/flows", + "pt-BR/concepts/knowledge", + "pt-BR/concepts/llms", + "pt-BR/concepts/processes", + "pt-BR/concepts/collaboration", + "pt-BR/concepts/training", + "pt-BR/concepts/memory", + "pt-BR/concepts/reasoning", + "pt-BR/concepts/planning", + "pt-BR/concepts/testing", + "pt-BR/concepts/cli", + "pt-BR/concepts/tools", + "pt-BR/concepts/event-listener" + ] + }, + { + "group": "Integração MCP", + "pages": [ + "pt-BR/mcp/overview", + "pt-BR/mcp/stdio", + "pt-BR/mcp/sse", + "pt-BR/mcp/streamable-http", + "pt-BR/mcp/multiple-servers", + "pt-BR/mcp/security" + ] + }, + { + "group": "Ferramentas", + "pages": [ + "pt-BR/tools/overview", + { + "group": "Arquivo & Documento", + "pages": [ + "pt-BR/tools/file-document/overview", + "pt-BR/tools/file-document/filereadtool", + "pt-BR/tools/file-document/filewritetool", + "pt-BR/tools/file-document/pdfsearchtool", + "pt-BR/tools/file-document/docxsearchtool", + "pt-BR/tools/file-document/mdxsearchtool", + "pt-BR/tools/file-document/xmlsearchtool", + "pt-BR/tools/file-document/txtsearchtool", + "pt-BR/tools/file-document/jsonsearchtool", + "pt-BR/tools/file-document/csvsearchtool", + "pt-BR/tools/file-document/directorysearchtool", + "pt-BR/tools/file-document/directoryreadtool" + ] + }, + { + "group": "Web Scraping & Navegação", + "pages": [ + "pt-BR/tools/web-scraping/overview", + "pt-BR/tools/web-scraping/scrapewebsitetool", + "pt-BR/tools/web-scraping/scrapeelementfromwebsitetool", + "pt-BR/tools/web-scraping/scrapflyscrapetool", + "pt-BR/tools/web-scraping/seleniumscrapingtool", + "pt-BR/tools/web-scraping/scrapegraphscrapetool", + "pt-BR/tools/web-scraping/spidertool", + "pt-BR/tools/web-scraping/browserbaseloadtool", + "pt-BR/tools/web-scraping/hyperbrowserloadtool", + "pt-BR/tools/web-scraping/stagehandtool", + "pt-BR/tools/web-scraping/firecrawlcrawlwebsitetool", + "pt-BR/tools/web-scraping/firecrawlscrapewebsitetool", + "pt-BR/tools/web-scraping/oxylabsscraperstool" + ] + }, + { + "group": "Pesquisa", + "pages": [ + "pt-BR/tools/search-research/overview", + "pt-BR/tools/search-research/serperdevtool", + "pt-BR/tools/search-research/bravesearchtool", + "pt-BR/tools/search-research/exasearchtool", + "pt-BR/tools/search-research/linkupsearchtool", + "pt-BR/tools/search-research/githubsearchtool", + "pt-BR/tools/search-research/websitesearchtool", + "pt-BR/tools/search-research/codedocssearchtool", + "pt-BR/tools/search-research/youtubechannelsearchtool", + "pt-BR/tools/search-research/youtubevideosearchtool" + ] + }, + { + "group": "Dados", + "pages": [ + "pt-BR/tools/database-data/overview", + "pt-BR/tools/database-data/mysqltool", + "pt-BR/tools/database-data/pgsearchtool", + "pt-BR/tools/database-data/snowflakesearchtool", + "pt-BR/tools/database-data/nl2sqltool", + "pt-BR/tools/database-data/qdrantvectorsearchtool", + "pt-BR/tools/database-data/weaviatevectorsearchtool" + ] + }, + { + "group": "IA & Machine Learning", + "pages": [ + "pt-BR/tools/ai-ml/overview", + "pt-BR/tools/ai-ml/dalletool", + "pt-BR/tools/ai-ml/visiontool", + "pt-BR/tools/ai-ml/aimindtool", + "pt-BR/tools/ai-ml/llamaindextool", + "pt-BR/tools/ai-ml/langchaintool", + "pt-BR/tools/ai-ml/ragtool", + "pt-BR/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "Cloud & Armazenamento", + "pages": [ + "pt-BR/tools/cloud-storage/overview", + "pt-BR/tools/cloud-storage/s3readertool", + "pt-BR/tools/cloud-storage/s3writertool", + "pt-BR/tools/cloud-storage/bedrockinvokeagenttool", + "pt-BR/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Automação & Integração", + "pages": [ + "pt-BR/tools/automation/overview", + "pt-BR/tools/automation/apifyactorstool", + "pt-BR/tools/automation/composiotool", + "pt-BR/tools/automation/multiontool" + ] + } + ] + }, + { + "group": "Observabilidade", + "pages": [ + "pt-BR/observability/overview", + "pt-BR/observability/agentops", + "pt-BR/observability/arize-phoenix", + "pt-BR/observability/langfuse", + "pt-BR/observability/langtrace", + "pt-BR/observability/maxim", + "pt-BR/observability/mlflow", + "pt-BR/observability/openlit", + "pt-BR/observability/opik", + "pt-BR/observability/patronus-evaluation", + "pt-BR/observability/portkey", + "pt-BR/observability/weave" + ] + }, + { + "group": "Aprenda", + "pages": [ + "pt-BR/learn/overview", + "pt-BR/learn/llm-selection-guide", + "pt-BR/learn/conditional-tasks", + "pt-BR/learn/coding-agents", + "pt-BR/learn/create-custom-tools", + "pt-BR/learn/custom-llm", + "pt-BR/learn/custom-manager-agent", + "pt-BR/learn/customizing-agents", + "pt-BR/learn/dalle-image-generation", + "pt-BR/learn/force-tool-output-as-result", + "pt-BR/learn/hierarchical-process", + "pt-BR/learn/human-input-on-execution", + "pt-BR/learn/kickoff-async", + "pt-BR/learn/kickoff-for-each", + "pt-BR/learn/llm-connections", + "pt-BR/learn/multimodal-agents", + "pt-BR/learn/replay-tasks-from-latest-crew-kickoff", + "pt-BR/learn/sequential-process", + "pt-BR/learn/using-annotations" + ] + }, + { + "group": "Telemetria", + "pages": [ + "pt-BR/telemetry" + ] + } ] }, { - "group": "Features", - "pages": [ - "enterprise/features/tool-repository", - "enterprise/features/webhook-streaming", - "enterprise/features/traces", - "enterprise/features/hallucination-guardrail", - "enterprise/features/integrations" + "tab": "Enterprise", + "groups": [ + { + "group": "Começando", + "pages": [ + "pt-BR/enterprise/introduction" + ] + }, + { + "group": "Funcionalidades", + "pages": [ + "pt-BR/enterprise/features/tool-repository", + "pt-BR/enterprise/features/webhook-streaming", + "pt-BR/enterprise/features/traces", + "pt-BR/enterprise/features/hallucination-guardrail", + "pt-BR/enterprise/features/integrations" + ] + }, + { + "group": "Documentação de Integração", + "pages": [ + "pt-BR/enterprise/integrations/asana", + "pt-BR/enterprise/integrations/box", + "pt-BR/enterprise/integrations/clickup", + "pt-BR/enterprise/integrations/github", + "pt-BR/enterprise/integrations/gmail", + "pt-BR/enterprise/integrations/google_calendar", + "pt-BR/enterprise/integrations/google_sheets", + "pt-BR/enterprise/integrations/hubspot", + "pt-BR/enterprise/integrations/jira", + "pt-BR/enterprise/integrations/linear", + "pt-BR/enterprise/integrations/notion", + "pt-BR/enterprise/integrations/salesforce", + "pt-BR/enterprise/integrations/shopify", + "pt-BR/enterprise/integrations/slack", + "pt-BR/enterprise/integrations/stripe", + "pt-BR/enterprise/integrations/zendesk" + ] + }, + { + "group": "Guias", + "pages": [ + "pt-BR/enterprise/guides/build-crew", + "pt-BR/enterprise/guides/deploy-crew", + "pt-BR/enterprise/guides/kickoff-crew", + "pt-BR/enterprise/guides/update-crew", + "pt-BR/enterprise/guides/enable-crew-studio", + "pt-BR/enterprise/guides/azure-openai-setup", + "pt-BR/enterprise/guides/hubspot-trigger", + "pt-BR/enterprise/guides/react-component-export", + "pt-BR/enterprise/guides/salesforce-trigger", + "pt-BR/enterprise/guides/slack-trigger", + "pt-BR/enterprise/guides/team-management", + "pt-BR/enterprise/guides/webhook-automation", + "pt-BR/enterprise/guides/human-in-the-loop", + "pt-BR/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "Recursos", + "pages": [ + "pt-BR/enterprise/resources/frequently-asked-questions" + ] + } ] }, { - "group": "Integration Docs", - "pages": [ - "enterprise/integrations/asana", - "enterprise/integrations/box", - "enterprise/integrations/clickup", - "enterprise/integrations/github", - "enterprise/integrations/gmail", - "enterprise/integrations/google_calendar", - "enterprise/integrations/google_sheets", - "enterprise/integrations/hubspot", - "enterprise/integrations/jira", - "enterprise/integrations/linear", - "enterprise/integrations/notion", - "enterprise/integrations/salesforce", - "enterprise/integrations/shopify", - "enterprise/integrations/slack", - "enterprise/integrations/stripe", - "enterprise/integrations/zendesk" + "tab": "Referência da API", + "groups": [ + { + "group": "Começando", + "pages": [ + "pt-BR/api-reference/introduction" + ] + }, + { + "group": "Endpoints", + "openapi": "enterprise-api.yaml" + } ] }, { - "group": "How-To Guides", - "pages": [ - "enterprise/guides/build-crew", - "enterprise/guides/deploy-crew", - "enterprise/guides/kickoff-crew", - "enterprise/guides/update-crew", - "enterprise/guides/enable-crew-studio", - "enterprise/guides/azure-openai-setup", - "enterprise/guides/hubspot-trigger", - "enterprise/guides/react-component-export", - "enterprise/guides/salesforce-trigger", - "enterprise/guides/slack-trigger", - "enterprise/guides/team-management", - "enterprise/guides/webhook-automation", - "enterprise/guides/human-in-the-loop", - "enterprise/guides/zapier-trigger" + "tab": "Exemplos", + "groups": [ + { + "group": "Exemplos", + "pages": [ + "pt-BR/examples/example" + ] + } ] }, { - "group": "Resources", - "pages": [ - "enterprise/resources/frequently-asked-questions" - ] - } - ] - }, - { - "tab": "API Reference", - "groups": [ - { - "group": "Getting Started", - "pages": [ - "api-reference/introduction" - ] - }, - { - "group": "Endpoints", - "openapi": "enterprise-api.yaml" - } - ] - }, - { - "tab": "Examples", - "groups": [ - { - "group": "Examples", - "pages": [ - "examples/example" - ] - } - ] - }, - { - "tab": "Releases", - "groups": [ - { - "group": "Releases", - "pages": [ - "changelog" + "tab": "Lançamentos", + "groups": [ + { + "group": "Lançamentos", + "pages": [ + "pt-BR/changelog" + ] + } ] } ] } - ], - "global": { - "anchors": [ - { - "anchor": "Website", - "href": "https://crewai.com", - "icon": "globe" - }, - { - "anchor": "Forum", - "href": "https://community.crewai.com", - "icon": "discourse" - }, - { - "anchor": "Crew GPT", - "href": "https://chatgpt.com/g/g-qqTuUWsBY-crewai-assistant", - "icon": "robot" - }, - { - "anchor": "Get Help", - "href": "mailto:support@crewai.com", - "icon": "headset" - } - ] - } + ] }, "logo": { - "light": "images/crew_only_logo.png", - "dark": "images/crew_only_logo.png" + "light": "/images/crew_only_logo.png", + "dark": "/images/crew_only_logo.png" }, "appearance": { "default": "dark", @@ -397,9 +764,6 @@ "href": "https://github.com/crewAIInc/crewAI" } }, - "search": { - "prompt": "Search CrewAI docs" - }, "api": { "baseUrl": "https://your-actual-crew-name.crewai.com", "auth": { diff --git a/docs/api-reference/introduction.mdx b/docs/en/api-reference/introduction.mdx similarity index 100% rename from docs/api-reference/introduction.mdx rename to docs/en/api-reference/introduction.mdx diff --git a/docs/changelog.mdx b/docs/en/changelog.mdx similarity index 100% rename from docs/changelog.mdx rename to docs/en/changelog.mdx diff --git a/docs/concepts/agents.mdx b/docs/en/concepts/agents.mdx similarity index 99% rename from docs/concepts/agents.mdx rename to docs/en/concepts/agents.mdx index 42d4de7c9..b8250f9f9 100644 --- a/docs/concepts/agents.mdx +++ b/docs/en/concepts/agents.mdx @@ -71,7 +71,7 @@ There are two ways to create agents in CrewAI: using **YAML configuration (recom Using YAML configuration provides a cleaner, more maintainable way to define agents. We strongly recommend using this approach in your CrewAI projects. -After creating your CrewAI project as outlined in the [Installation](/installation) section, navigate to the `src/latest_ai_development/config/agents.yaml` file and modify the template to match your requirements. +After creating your CrewAI project as outlined in the [Installation](/en/installation) section, navigate to the `src/latest_ai_development/config/agents.yaml` file and modify the template to match your requirements. Variables in your YAML files (like `{topic}`) will be replaced with values from your inputs when running the crew: @@ -312,7 +312,7 @@ multimodal_agent = Agent( When using custom templates, ensure that both `system_template` and `prompt_template` are defined. The `response_template` is optional but recommended for consistent output formatting. - + When using custom templates, you can use variables like `{role}`, `{goal}`, and `{backstory}` in your templates. These will be automatically populated during execution. @@ -425,7 +425,7 @@ strict_agent = Agent( ```python Code # Perfect for document processing document_processor = Agent( - role="Document Analyst", + role="Document Analyst", goal="Extract insights from large research papers", backstory="Expert at analyzing extensive documentation", respect_context_window=True, # Handle large documents gracefully diff --git a/docs/concepts/cli.mdx b/docs/en/concepts/cli.mdx similarity index 100% rename from docs/concepts/cli.mdx rename to docs/en/concepts/cli.mdx diff --git a/docs/concepts/collaboration.mdx b/docs/en/concepts/collaboration.mdx similarity index 100% rename from docs/concepts/collaboration.mdx rename to docs/en/concepts/collaboration.mdx diff --git a/docs/concepts/crews.mdx b/docs/en/concepts/crews.mdx similarity index 98% rename from docs/concepts/crews.mdx rename to docs/en/concepts/crews.mdx index 7bce57854..3c6f4b507 100644 --- a/docs/concepts/crews.mdx +++ b/docs/en/concepts/crews.mdx @@ -45,7 +45,7 @@ There are two ways to create crews in CrewAI: using **YAML configuration (recomm Using YAML configuration provides a cleaner, more maintainable way to define crews and is consistent with how agents and tasks are defined in CrewAI projects. -After creating your CrewAI project as outlined in the [Installation](/installation) section, you can define your crew in a class that inherits from `CrewBase` and uses decorators to define agents, tasks, and the crew itself. +After creating your CrewAI project as outlined in the [Installation](/en/installation) section, you can define your crew in a class that inherits from `CrewBase` and uses decorators to define agents, tasks, and the crew itself. #### Example Crew Class with Decorators @@ -66,8 +66,8 @@ class YourCrewName: # To see an example agent and task defined in YAML, checkout the following: # - 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' + agents_config = 'config/agents.yaml' + tasks_config = 'config/tasks.yaml' @before_kickoff def prepare_inputs(self, inputs): @@ -111,7 +111,7 @@ class YourCrewName: def crew(self) -> Crew: return Crew( agents=self.agents, # Automatically collected by the @agent decorator - tasks=self.tasks, # Automatically collected by the @task decorator. + tasks=self.tasks, # Automatically collected by the @task decorator. process=Process.sequential, verbose=True, ) diff --git a/docs/concepts/event-listener.mdx b/docs/en/concepts/event-listener.mdx similarity index 100% rename from docs/concepts/event-listener.mdx rename to docs/en/concepts/event-listener.mdx diff --git a/docs/concepts/flows.mdx b/docs/en/concepts/flows.mdx similarity index 100% rename from docs/concepts/flows.mdx rename to docs/en/concepts/flows.mdx diff --git a/docs/concepts/knowledge.mdx b/docs/en/concepts/knowledge.mdx similarity index 100% rename from docs/concepts/knowledge.mdx rename to docs/en/concepts/knowledge.mdx diff --git a/docs/concepts/llms.mdx b/docs/en/concepts/llms.mdx similarity index 100% rename from docs/concepts/llms.mdx rename to docs/en/concepts/llms.mdx diff --git a/docs/concepts/memory.mdx b/docs/en/concepts/memory.mdx similarity index 100% rename from docs/concepts/memory.mdx rename to docs/en/concepts/memory.mdx diff --git a/docs/concepts/planning.mdx b/docs/en/concepts/planning.mdx similarity index 100% rename from docs/concepts/planning.mdx rename to docs/en/concepts/planning.mdx diff --git a/docs/concepts/processes.mdx b/docs/en/concepts/processes.mdx similarity index 100% rename from docs/concepts/processes.mdx rename to docs/en/concepts/processes.mdx diff --git a/docs/concepts/reasoning.mdx b/docs/en/concepts/reasoning.mdx similarity index 100% rename from docs/concepts/reasoning.mdx rename to docs/en/concepts/reasoning.mdx diff --git a/docs/concepts/tasks.mdx b/docs/en/concepts/tasks.mdx similarity index 99% rename from docs/concepts/tasks.mdx rename to docs/en/concepts/tasks.mdx index 0952203d4..da74d85a9 100644 --- a/docs/concepts/tasks.mdx +++ b/docs/en/concepts/tasks.mdx @@ -66,7 +66,7 @@ There are two ways to create tasks in CrewAI: using **YAML configuration (recomm Using YAML configuration provides a cleaner, more maintainable way to define tasks. We strongly recommend using this approach to define tasks in your CrewAI projects. -After creating your CrewAI project as outlined in the [Installation](/installation) section, navigate to the `src/latest_ai_development/config/tasks.yaml` file and modify the template to match your specific task requirements. +After creating your CrewAI project as outlined in the [Installation](/en/installation) section, navigate to the `src/latest_ai_development/config/tasks.yaml` file and modify the template to match your specific task requirements. Variables in your YAML files (like `{topic}`) will be replaced with values from your inputs when running the crew: @@ -277,7 +277,7 @@ formatted_task = Task( When `markdown=True`, the agent will receive additional instructions to format the output using: - `#` for headers -- `**text**` for bold text +- `**text**` for bold text - `*text*` for italic text - `-` or `*` for bullet points - `` `code` `` for inline code diff --git a/docs/concepts/testing.mdx b/docs/en/concepts/testing.mdx similarity index 100% rename from docs/concepts/testing.mdx rename to docs/en/concepts/testing.mdx diff --git a/docs/concepts/tools.mdx b/docs/en/concepts/tools.mdx similarity index 100% rename from docs/concepts/tools.mdx rename to docs/en/concepts/tools.mdx diff --git a/docs/concepts/training.mdx b/docs/en/concepts/training.mdx similarity index 100% rename from docs/concepts/training.mdx rename to docs/en/concepts/training.mdx diff --git a/docs/enterprise/features/hallucination-guardrail.mdx b/docs/en/enterprise/features/hallucination-guardrail.mdx similarity index 100% rename from docs/enterprise/features/hallucination-guardrail.mdx rename to docs/en/enterprise/features/hallucination-guardrail.mdx diff --git a/docs/enterprise/features/integrations.mdx b/docs/en/enterprise/features/integrations.mdx similarity index 100% rename from docs/enterprise/features/integrations.mdx rename to docs/en/enterprise/features/integrations.mdx diff --git a/docs/enterprise/features/tool-repository.mdx b/docs/en/enterprise/features/tool-repository.mdx similarity index 100% rename from docs/enterprise/features/tool-repository.mdx rename to docs/en/enterprise/features/tool-repository.mdx diff --git a/docs/enterprise/features/traces.mdx b/docs/en/enterprise/features/traces.mdx similarity index 100% rename from docs/enterprise/features/traces.mdx rename to docs/en/enterprise/features/traces.mdx diff --git a/docs/enterprise/features/webhook-streaming.mdx b/docs/en/enterprise/features/webhook-streaming.mdx similarity index 100% rename from docs/enterprise/features/webhook-streaming.mdx rename to docs/en/enterprise/features/webhook-streaming.mdx diff --git a/docs/enterprise/guides/azure-openai-setup.mdx b/docs/en/enterprise/guides/azure-openai-setup.mdx similarity index 100% rename from docs/enterprise/guides/azure-openai-setup.mdx rename to docs/en/enterprise/guides/azure-openai-setup.mdx diff --git a/docs/enterprise/guides/build-crew.mdx b/docs/en/enterprise/guides/build-crew.mdx similarity index 89% rename from docs/enterprise/guides/build-crew.mdx rename to docs/en/enterprise/guides/build-crew.mdx index 9595f5b88..d403b80ed 100644 --- a/docs/enterprise/guides/build-crew.mdx +++ b/docs/en/enterprise/guides/build-crew.mdx @@ -10,11 +10,11 @@ icon: "people-arrows" ## Getting Started - @@ -148,4 +148,4 @@ icon: "circle-question" The `max_rpm` attribute sets the maximum number of requests per minute the crew can perform to avoid rate limits and will override individual agents' `max_rpm` settings if you set it. - \ No newline at end of file + diff --git a/docs/examples/example.mdx b/docs/en/examples/example.mdx similarity index 100% rename from docs/examples/example.mdx rename to docs/en/examples/example.mdx diff --git a/docs/guides/advanced/customizing-prompts.mdx b/docs/en/guides/advanced/customizing-prompts.mdx similarity index 97% rename from docs/guides/advanced/customizing-prompts.mdx rename to docs/en/guides/advanced/customizing-prompts.mdx index 72850bc99..50de24538 100644 --- a/docs/guides/advanced/customizing-prompts.mdx +++ b/docs/en/guides/advanced/customizing-prompts.mdx @@ -44,7 +44,7 @@ Based on your agent configuration, CrewAI adds different default instructions: "I MUST use these formats, my job depends on it!" ``` -#### For Agents With Tools +#### For Agents With Tools ```text "IMPORTANT: Use the following format in your response: @@ -127,7 +127,7 @@ custom_prompt_template = """Task: {input} Please complete this task thoughtfully.""" agent = Agent( - role="Research Assistant", + role="Research Assistant", goal="Help users find accurate information", backstory="You are a helpful research assistant.", system_template=custom_system_template, @@ -164,7 +164,7 @@ crew = Crew( ```python agent = Agent( role="Analyst", - goal="Analyze data", + goal="Analyze data", backstory="Expert analyst", use_system_prompt=False # Disables system prompt separation ) @@ -174,13 +174,13 @@ agent = Agent( For production transparency, integrate with observability platforms to monitor all prompts and LLM interactions. This allows you to see exactly what prompts (including default instructions) are being sent to your LLMs. -See our [Observability documentation](/how-to/observability) for detailed integration guides with various platforms including Langfuse, MLflow, Weights & Biases, and custom logging solutions. +See our [Observability documentation](/en/observability/overview) for detailed integration guides with various platforms including Langfuse, MLflow, Weights & Biases, and custom logging solutions. ### Best Practices for Production 1. **Always inspect generated prompts** before deploying to production 2. **Use custom templates** when you need full control over prompt content -3. **Integrate observability tools** for ongoing prompt monitoring (see [Observability docs](/how-to/observability)) +3. **Integrate observability tools** for ongoing prompt monitoring (see [Observability docs](/en/observability/overview)) 4. **Test with different LLMs** as default instructions may work differently across models 5. **Document your prompt customizations** for team transparency @@ -313,4 +313,4 @@ Low-level prompt customization in CrewAI opens the door to super custom, complex You now have the foundation for advanced prompt customizations in CrewAI. Whether you're adapting for model-specific structures or domain-specific constraints, this low-level approach lets you shape agent interactions in highly specialized ways. - \ No newline at end of file + diff --git a/docs/guides/advanced/fingerprinting.mdx b/docs/en/guides/advanced/fingerprinting.mdx similarity index 100% rename from docs/guides/advanced/fingerprinting.mdx rename to docs/en/guides/advanced/fingerprinting.mdx diff --git a/docs/guides/agents/crafting-effective-agents.mdx b/docs/en/guides/agents/crafting-effective-agents.mdx similarity index 99% rename from docs/guides/agents/crafting-effective-agents.mdx rename to docs/en/guides/agents/crafting-effective-agents.mdx index 3eb208b0a..915bf5340 100644 --- a/docs/guides/agents/crafting-effective-agents.mdx +++ b/docs/en/guides/agents/crafting-effective-agents.mdx @@ -448,5 +448,5 @@ Congratulations! You now understand the principles and practices of effective ag ## Next Steps - Experiment with different agent configurations for your specific use case -- Learn about [building your first crew](/guides/crews/first-crew) to see how agents work together -- Explore [CrewAI Flows](/guides/flows/first-flow) for more advanced orchestration \ No newline at end of file +- Learn about [building your first crew](/en/guides/crews/first-crew) to see how agents work together +- Explore [CrewAI Flows](/en/guides/flows/first-flow) for more advanced orchestration diff --git a/docs/guides/concepts/evaluating-use-cases.mdx b/docs/en/guides/concepts/evaluating-use-cases.mdx similarity index 97% rename from docs/guides/concepts/evaluating-use-cases.mdx rename to docs/en/guides/concepts/evaluating-use-cases.mdx index 3cf2ca523..b514edea0 100644 --- a/docs/guides/concepts/evaluating-use-cases.mdx +++ b/docs/en/guides/concepts/evaluating-use-cases.mdx @@ -11,7 +11,7 @@ When building AI applications with CrewAI, one of the most important decisions y At the heart of this decision is understanding the relationship between **complexity** and **precision** in your application: - Complexity vs. Precision Matrix + Complexity vs. Precision Matrix This matrix helps visualize how different approaches align with varying requirements for complexity and precision. Let's explore what each quadrant means and how it guides your architectural choices. @@ -497,7 +497,7 @@ You now have a framework for evaluating CrewAI use cases and choosing the right ## Next Steps -- Learn more about [crafting effective agents](/guides/agents/crafting-effective-agents) -- Explore [building your first crew](/guides/crews/first-crew) -- Dive into [mastering flow state management](/guides/flows/mastering-flow-state) -- Check out the [core concepts](/concepts/agents) for deeper understanding \ No newline at end of file +- Learn more about [crafting effective agents](/en/guides/agents/crafting-effective-agents) +- Explore [building your first crew](/en/guides/crews/first-crew) +- Dive into [mastering flow state management](/en/guides/flows/mastering-flow-state) +- Check out the [core concepts](/en/concepts/agents) for deeper understanding diff --git a/docs/guides/crews/first-crew.mdx b/docs/en/guides/crews/first-crew.mdx similarity index 96% rename from docs/guides/crews/first-crew.mdx rename to docs/en/guides/crews/first-crew.mdx index 6cd35aebf..95c2bbf66 100644 --- a/docs/guides/crews/first-crew.mdx +++ b/docs/en/guides/crews/first-crew.mdx @@ -32,9 +32,9 @@ Let's get started building your first crew! Before starting, make sure you have: -1. Installed CrewAI following the [installation guide](/installation) +1. Installed CrewAI following the [installation guide](/en/installation) 2. Set up your LLM API key in your environment, following the [LLM setup - guide](/concepts/llms#setting-up-your-llm) + guide](/en/concepts/llms#setting-up-your-llm) 3. Basic understanding of Python ## Step 1: Create a New CrewAI Project @@ -54,7 +54,7 @@ This will generate a project with the basic structure needed for your crew. The - A main script to run the crew - CrewAI Framework Overview + CrewAI Framework Overview @@ -287,7 +287,7 @@ SERPER_API_KEY=your_serper_api_key # Add your provider's API key here too. ``` -See the [LLM Setup guide](/concepts/llms#setting-up-your-llm) for details on configuring your provider of choice. You can get a Serper API key from [Serper.dev](https://serper.dev/). +See the [LLM Setup guide](/en/concepts/llms#setting-up-your-llm) for details on configuring your provider of choice. You can get a Serper API key from [Serper.dev](https://serper.dev/). ## Step 8: Install Dependencies @@ -388,7 +388,7 @@ Now that you've built your first crew, you can: 2. Try more complex task structures and workflows 3. Implement custom tools to give your agents new capabilities 4. Apply your crew to different topics or problem domains -5. Explore [CrewAI Flows](/guides/flows/first-flow) for more advanced workflows with procedural programming +5. Explore [CrewAI Flows](/en/guides/flows/first-flow) for more advanced workflows with procedural programming Congratulations! You've successfully built your first CrewAI crew that can research and analyze any topic you provide. This foundational experience has equipped you with the skills to create increasingly sophisticated AI systems that can tackle complex, multi-stage problems through collaborative intelligence. diff --git a/docs/guides/flows/first-flow.mdx b/docs/en/guides/flows/first-flow.mdx similarity index 98% rename from docs/guides/flows/first-flow.mdx rename to docs/en/guides/flows/first-flow.mdx index 3aa9a7ac6..57251879b 100644 --- a/docs/guides/flows/first-flow.mdx +++ b/docs/en/guides/flows/first-flow.mdx @@ -42,9 +42,9 @@ Let's dive in and build your first flow! Before starting, make sure you have: -1. Installed CrewAI following the [installation guide](/installation) +1. Installed CrewAI following the [installation guide](/en/installation) 2. Set up your LLM API key in your environment, following the [LLM setup - guide](/concepts/llms#setting-up-your-llm) + guide](/en/concepts/llms#setting-up-your-llm) 3. Basic understanding of Python ## Step 1: Create a New CrewAI Flow Project @@ -59,7 +59,7 @@ cd guide_creator_flow This will generate a project with the basic structure needed for your flow. - CrewAI Framework Overview + CrewAI Framework Overview ## Step 2: Understanding the Project Structure @@ -443,7 +443,7 @@ This is the power of flows - combining different types of processing (user inter ## Step 6: Set Up Your Environment Variables Create a `.env` file in your project root with your API keys. See the [LLM setup -guide](/concepts/llms#setting-up-your-llm) for details on configuring a provider. +guide](/en/concepts/llms#setting-up-your-llm) for details on configuring a provider. ```sh .env OPENAI_API_KEY=your_openai_api_key diff --git a/docs/guides/flows/mastering-flow-state.mdx b/docs/en/guides/flows/mastering-flow-state.mdx similarity index 99% rename from docs/guides/flows/mastering-flow-state.mdx rename to docs/en/guides/flows/mastering-flow-state.mdx index ad61a05fe..4d1fac515 100644 --- a/docs/guides/flows/mastering-flow-state.mdx +++ b/docs/en/guides/flows/mastering-flow-state.mdx @@ -767,5 +767,5 @@ You've now mastered the concepts and practices of state management in CrewAI Flo - Experiment with both structured and unstructured state in your flows - Try implementing state persistence for long-running workflows -- Explore [building your first crew](/guides/crews/first-crew) to see how crews and flows can work together -- Check out the [Flow reference documentation](/concepts/flows) for more advanced features \ No newline at end of file +- Explore [building your first crew](/en/guides/crews/first-crew) to see how crews and flows can work together +- Check out the [Flow reference documentation](/en/concepts/flows) for more advanced features diff --git a/docs/installation.mdx b/docs/en/installation.mdx similarity index 99% rename from docs/installation.mdx rename to docs/en/installation.mdx index fedc374f0..3a2b342cc 100644 --- a/docs/installation.mdx +++ b/docs/en/installation.mdx @@ -186,7 +186,7 @@ For teams and organizations, CrewAI offers enterprise deployment options that el Follow our quickstart guide to create your first CrewAI agent and get hands-on experience. diff --git a/docs/introduction.mdx b/docs/en/introduction.mdx similarity index 77% rename from docs/introduction.mdx rename to docs/en/introduction.mdx index 23c1c38a7..eb52b41ce 100644 --- a/docs/introduction.mdx +++ b/docs/en/introduction.mdx @@ -10,8 +10,8 @@ icon: handshake CrewAI empowers developers with both high-level simplicity and precise low-level control, ideal for creating autonomous AI agents tailored to any scenario: -- **[CrewAI Crews](/guides/crews/first-crew)**: Optimize for autonomy and collaborative intelligence, enabling you to create AI teams where each agent has specific roles, tools, and goals. -- **[CrewAI Flows](/guides/flows/first-flow)**: Enable granular, event-driven control, single LLM calls for precise task orchestration and supports Crews natively. +- **[CrewAI Crews](/en/guides/crews/first-crew)**: Optimize for autonomy and collaborative intelligence, enabling you to create AI teams where each agent has specific roles, tools, and goals. +- **[CrewAI Flows](/en/guides/flows/first-flow)**: Enable granular, event-driven control, single LLM calls for precise task orchestration and supports Crews natively. With over 100,000 developers certified through our community courses, CrewAI is rapidly becoming the standard for enterprise-ready AI automation. @@ -23,7 +23,7 @@ With over 100,000 developers certified through our community courses, CrewAI is - CrewAI Framework Overview + CrewAI Framework Overview | Component | Description | Key Features | @@ -64,7 +64,7 @@ With over 100,000 developers certified through our community courses, CrewAI is - CrewAI Framework Overview + CrewAI Framework Overview | Component | Description | Key Features | @@ -94,21 +94,21 @@ With over 100,000 developers certified through our community courses, CrewAI is ## When to Use Crews vs. Flows - Understanding when to use [Crews](/guides/crews/first-crew) versus [Flows](/guides/flows/first-flow) is key to maximizing the potential of CrewAI in your applications. + Understanding when to use [Crews](/en/guides/crews/first-crew) versus [Flows](/en/guides/flows/first-flow) is key to maximizing the potential of CrewAI in your applications. | Use Case | Recommended Approach | Why? | |:---------|:---------------------|:-----| -| **Open-ended research** | [Crews](/guides/crews/first-crew) | When tasks require creative thinking, exploration, and adaptation | -| **Content generation** | [Crews](/guides/crews/first-crew) | For collaborative creation of articles, reports, or marketing materials | -| **Decision workflows** | [Flows](/guides/flows/first-flow) | When you need predictable, auditable decision paths with precise control | -| **API orchestration** | [Flows](/guides/flows/first-flow) | For reliable integration with multiple external services in a specific sequence | -| **Hybrid applications** | Combined approach | Use [Flows](/guides/flows/first-flow) to orchestrate overall process with [Crews](/guides/crews/first-crew) handling complex subtasks | +| **Open-ended research** | [Crews](/en/guides/crews/first-crew) | When tasks require creative thinking, exploration, and adaptation | +| **Content generation** | [Crews](/en/guides/crews/first-crew) | For collaborative creation of articles, reports, or marketing materials | +| **Decision workflows** | [Flows](/en/guides/flows/first-flow) | When you need predictable, auditable decision paths with precise control | +| **API orchestration** | [Flows](/en/guides/flows/first-flow) | For reliable integration with multiple external services in a specific sequence | +| **Hybrid applications** | Combined approach | Use [Flows](/en/guides/flows/first-flow) to orchestrate overall process with [Crews](/en/guides/crews/first-crew) handling complex subtasks | ### Decision Framework -- **Choose [Crews](/guides/crews/first-crew) when:** You need autonomous problem-solving, creative collaboration, or exploratory tasks -- **Choose [Flows](/guides/flows/first-flow) when:** You require deterministic outcomes, auditability, or precise control over execution +- **Choose [Crews](/en/guides/crews/first-crew) when:** You need autonomous problem-solving, creative collaboration, or exploratory tasks +- **Choose [Flows](/en/guides/flows/first-flow) when:** You require deterministic outcomes, auditability, or precise control over execution - **Combine both when:** Your application needs both structured processes and pockets of autonomous intelligence ## Why Choose CrewAI? @@ -126,14 +126,14 @@ With over 100,000 developers certified through our community courses, CrewAI is Step-by-step tutorial to create a collaborative AI team that works together to solve complex problems. Learn how to create structured, event-driven workflows with precise control over execution. @@ -143,14 +143,14 @@ With over 100,000 developers certified through our community courses, CrewAI is Get started with CrewAI in your development environment. Follow our quickstart guide to create your first CrewAI agent and get hands-on experience. @@ -161,4 +161,4 @@ With over 100,000 developers certified through our community courses, CrewAI is > Connect with other developers, get help, and share your CrewAI experiences. - \ No newline at end of file + diff --git a/docs/learn/before-and-after-kickoff-hooks.mdx b/docs/en/learn/before-and-after-kickoff-hooks.mdx similarity index 100% rename from docs/learn/before-and-after-kickoff-hooks.mdx rename to docs/en/learn/before-and-after-kickoff-hooks.mdx diff --git a/docs/learn/bring-your-own-agent.mdx b/docs/en/learn/bring-your-own-agent.mdx similarity index 100% rename from docs/learn/bring-your-own-agent.mdx rename to docs/en/learn/bring-your-own-agent.mdx diff --git a/docs/learn/coding-agents.mdx b/docs/en/learn/coding-agents.mdx similarity index 100% rename from docs/learn/coding-agents.mdx rename to docs/en/learn/coding-agents.mdx diff --git a/docs/learn/conditional-tasks.mdx b/docs/en/learn/conditional-tasks.mdx similarity index 100% rename from docs/learn/conditional-tasks.mdx rename to docs/en/learn/conditional-tasks.mdx diff --git a/docs/learn/create-custom-tools.mdx b/docs/en/learn/create-custom-tools.mdx similarity index 100% rename from docs/learn/create-custom-tools.mdx rename to docs/en/learn/create-custom-tools.mdx diff --git a/docs/learn/custom-llm.mdx b/docs/en/learn/custom-llm.mdx similarity index 100% rename from docs/learn/custom-llm.mdx rename to docs/en/learn/custom-llm.mdx diff --git a/docs/learn/custom-manager-agent.mdx b/docs/en/learn/custom-manager-agent.mdx similarity index 100% rename from docs/learn/custom-manager-agent.mdx rename to docs/en/learn/custom-manager-agent.mdx diff --git a/docs/learn/customizing-agents.mdx b/docs/en/learn/customizing-agents.mdx similarity index 100% rename from docs/learn/customizing-agents.mdx rename to docs/en/learn/customizing-agents.mdx diff --git a/docs/learn/dalle-image-generation.mdx b/docs/en/learn/dalle-image-generation.mdx similarity index 100% rename from docs/learn/dalle-image-generation.mdx rename to docs/en/learn/dalle-image-generation.mdx diff --git a/docs/learn/force-tool-output-as-result.mdx b/docs/en/learn/force-tool-output-as-result.mdx similarity index 100% rename from docs/learn/force-tool-output-as-result.mdx rename to docs/en/learn/force-tool-output-as-result.mdx diff --git a/docs/learn/hierarchical-process.mdx b/docs/en/learn/hierarchical-process.mdx similarity index 100% rename from docs/learn/hierarchical-process.mdx rename to docs/en/learn/hierarchical-process.mdx diff --git a/docs/learn/human-in-the-loop.mdx b/docs/en/learn/human-in-the-loop.mdx similarity index 100% rename from docs/learn/human-in-the-loop.mdx rename to docs/en/learn/human-in-the-loop.mdx diff --git a/docs/learn/human-input-on-execution.mdx b/docs/en/learn/human-input-on-execution.mdx similarity index 100% rename from docs/learn/human-input-on-execution.mdx rename to docs/en/learn/human-input-on-execution.mdx diff --git a/docs/learn/kickoff-async.mdx b/docs/en/learn/kickoff-async.mdx similarity index 100% rename from docs/learn/kickoff-async.mdx rename to docs/en/learn/kickoff-async.mdx diff --git a/docs/learn/kickoff-for-each.mdx b/docs/en/learn/kickoff-for-each.mdx similarity index 100% rename from docs/learn/kickoff-for-each.mdx rename to docs/en/learn/kickoff-for-each.mdx diff --git a/docs/learn/llm-connections.mdx b/docs/en/learn/llm-connections.mdx similarity index 100% rename from docs/learn/llm-connections.mdx rename to docs/en/learn/llm-connections.mdx diff --git a/docs/learn/llm-selection-guide.mdx b/docs/en/learn/llm-selection-guide.mdx similarity index 100% rename from docs/learn/llm-selection-guide.mdx rename to docs/en/learn/llm-selection-guide.mdx diff --git a/docs/learn/multimodal-agents.mdx b/docs/en/learn/multimodal-agents.mdx similarity index 100% rename from docs/learn/multimodal-agents.mdx rename to docs/en/learn/multimodal-agents.mdx diff --git a/docs/learn/overview.mdx b/docs/en/learn/overview.mdx similarity index 76% rename from docs/learn/overview.mdx rename to docs/en/learn/overview.mdx index f2c942690..4494731ad 100644 --- a/docs/learn/overview.mdx +++ b/docs/en/learn/overview.mdx @@ -12,38 +12,38 @@ This section provides comprehensive guides and tutorials to help you master Crew ### Core Concepts - + Learn how to execute tasks in a sequential order for structured workflows. - + Implement hierarchical task execution with manager agents overseeing workflows. - + Create dynamic workflows with conditional task execution based on outcomes. - + Execute crews asynchronously for improved performance and concurrency. ### Agent Development - + Learn how to customize agent behavior, roles, and capabilities. - + Build agents that can write, execute, and debug code automatically. - + Create agents that can process text, images, and other media types. - + Implement custom manager agents for complex hierarchical workflows. @@ -52,38 +52,38 @@ This section provides comprehensive guides and tutorials to help you master Crew ### Workflow Control - + Integrate human oversight and intervention into agent workflows. - + Allow human input during task execution for dynamic decision making. - + Replay and resume tasks from previous crew executions. - + Execute crews multiple times with different inputs efficiently. ### Customization & Integration - + Integrate custom language models and providers with CrewAI. - + Configure and manage connections to various LLM providers. - + Build custom tools to extend agent capabilities. - + Use Python annotations for cleaner, more maintainable code. @@ -92,18 +92,18 @@ This section provides comprehensive guides and tutorials to help you master Crew ### Content & Media - + Generate images using DALL-E integration with your agents. - + Integrate existing agents and models into CrewAI workflows. ### Tool Management - + Configure tools to return their output directly as task results. @@ -155,4 +155,4 @@ This section provides comprehensive guides and tutorials to help you master Crew - **Examples**: Check the Examples section for complete working implementations - **Support**: Contact [support@crewai.com](mailto:support@crewai.com) for technical assistance -Start with the guides that match your current needs and gradually explore more advanced topics as you become comfortable with the fundamentals. \ No newline at end of file +Start with the guides that match your current needs and gradually explore more advanced topics as you become comfortable with the fundamentals. diff --git a/docs/learn/replay-tasks-from-latest-crew-kickoff.mdx b/docs/en/learn/replay-tasks-from-latest-crew-kickoff.mdx similarity index 100% rename from docs/learn/replay-tasks-from-latest-crew-kickoff.mdx rename to docs/en/learn/replay-tasks-from-latest-crew-kickoff.mdx diff --git a/docs/learn/sequential-process.mdx b/docs/en/learn/sequential-process.mdx similarity index 100% rename from docs/learn/sequential-process.mdx rename to docs/en/learn/sequential-process.mdx diff --git a/docs/learn/using-annotations.mdx b/docs/en/learn/using-annotations.mdx similarity index 100% rename from docs/learn/using-annotations.mdx rename to docs/en/learn/using-annotations.mdx diff --git a/docs/mcp/multiple-servers.mdx b/docs/en/mcp/multiple-servers.mdx similarity index 100% rename from docs/mcp/multiple-servers.mdx rename to docs/en/mcp/multiple-servers.mdx diff --git a/docs/mcp/overview.mdx b/docs/en/mcp/overview.mdx similarity index 98% rename from docs/mcp/overview.mdx rename to docs/en/mcp/overview.mdx index 19943ca00..c2543d779 100644 --- a/docs/mcp/overview.mdx +++ b/docs/en/mcp/overview.mdx @@ -142,7 +142,7 @@ class CrewWithMCP: Connect to local MCP servers via standard input/output. Ideal for scripts and local executables. @@ -150,7 +150,7 @@ class CrewWithMCP: Integrate with remote MCP servers using Server-Sent Events for real-time data streaming. @@ -158,7 +158,7 @@ class CrewWithMCP: Utilize flexible Streamable HTTP for robust communication with remote MCP servers. @@ -166,7 +166,7 @@ class CrewWithMCP: Aggregate tools from several MCP servers simultaneously using a single adapter. @@ -174,7 +174,7 @@ class CrewWithMCP: Review important security best practices for MCP integration to keep your agents safe. diff --git a/docs/mcp/security.mdx b/docs/en/mcp/security.mdx similarity index 100% rename from docs/mcp/security.mdx rename to docs/en/mcp/security.mdx diff --git a/docs/mcp/sse.mdx b/docs/en/mcp/sse.mdx similarity index 100% rename from docs/mcp/sse.mdx rename to docs/en/mcp/sse.mdx diff --git a/docs/mcp/stdio.mdx b/docs/en/mcp/stdio.mdx similarity index 100% rename from docs/mcp/stdio.mdx rename to docs/en/mcp/stdio.mdx diff --git a/docs/mcp/streamable-http.mdx b/docs/en/mcp/streamable-http.mdx similarity index 100% rename from docs/mcp/streamable-http.mdx rename to docs/en/mcp/streamable-http.mdx diff --git a/docs/observability/agentops.mdx b/docs/en/observability/agentops.mdx similarity index 100% rename from docs/observability/agentops.mdx rename to docs/en/observability/agentops.mdx diff --git a/docs/observability/arize-phoenix.mdx b/docs/en/observability/arize-phoenix.mdx similarity index 100% rename from docs/observability/arize-phoenix.mdx rename to docs/en/observability/arize-phoenix.mdx diff --git a/docs/observability/langfuse.mdx b/docs/en/observability/langfuse.mdx similarity index 100% rename from docs/observability/langfuse.mdx rename to docs/en/observability/langfuse.mdx diff --git a/docs/observability/langtrace.mdx b/docs/en/observability/langtrace.mdx similarity index 100% rename from docs/observability/langtrace.mdx rename to docs/en/observability/langtrace.mdx diff --git a/docs/observability/maxim.mdx b/docs/en/observability/maxim.mdx similarity index 100% rename from docs/observability/maxim.mdx rename to docs/en/observability/maxim.mdx diff --git a/docs/observability/mlflow.mdx b/docs/en/observability/mlflow.mdx similarity index 100% rename from docs/observability/mlflow.mdx rename to docs/en/observability/mlflow.mdx diff --git a/docs/observability/openlit.mdx b/docs/en/observability/openlit.mdx similarity index 100% rename from docs/observability/openlit.mdx rename to docs/en/observability/openlit.mdx diff --git a/docs/observability/opik.mdx b/docs/en/observability/opik.mdx similarity index 100% rename from docs/observability/opik.mdx rename to docs/en/observability/opik.mdx diff --git a/docs/observability/overview.mdx b/docs/en/observability/overview.mdx similarity index 82% rename from docs/observability/overview.mdx rename to docs/en/observability/overview.mdx index 72d4ec276..47ee356d4 100644 --- a/docs/observability/overview.mdx +++ b/docs/en/observability/overview.mdx @@ -21,39 +21,39 @@ Observability is crucial for understanding how your CrewAI agents perform, ident ### Monitoring & Tracing Platforms - + Session replays, metrics, and monitoring for agent development and production. - + OpenTelemetry-native monitoring with cost tracking and performance analytics. - + Machine learning lifecycle management with tracing and evaluation capabilities. - + LLM engineering platform with detailed tracing and analytics. - + Open-source observability for LLMs and agent frameworks. - + AI observability platform for monitoring and troubleshooting. - + AI gateway with comprehensive monitoring and reliability features. - + Debug, evaluate, and monitor LLM applications with comprehensive tracing. - + Weights & Biases platform for tracking and evaluating AI applications. @@ -61,7 +61,7 @@ Observability is crucial for understanding how your CrewAI agents perform, ident ### Evaluation & Quality Assurance - + Comprehensive evaluation platform for LLM outputs and agent behaviors. @@ -115,4 +115,4 @@ Observability is crucial for understanding how your CrewAI agents perform, ident - Feedback loops for quality improvement - Documentation of lessons learned -Choose the observability tools that best fit your use case, infrastructure, and monitoring requirements to ensure your CrewAI agents perform reliably and efficiently. \ No newline at end of file +Choose the observability tools that best fit your use case, infrastructure, and monitoring requirements to ensure your CrewAI agents perform reliably and efficiently. diff --git a/docs/observability/patronus-evaluation.mdx b/docs/en/observability/patronus-evaluation.mdx similarity index 100% rename from docs/observability/patronus-evaluation.mdx rename to docs/en/observability/patronus-evaluation.mdx diff --git a/docs/observability/portkey.mdx b/docs/en/observability/portkey.mdx similarity index 99% rename from docs/observability/portkey.mdx rename to docs/en/observability/portkey.mdx index a2f66f566..eb2fa9960 100644 --- a/docs/observability/portkey.mdx +++ b/docs/en/observability/portkey.mdx @@ -734,7 +734,7 @@ Here's a basic configuration to route requests to OpenAI, specifically using GPT Create API keys through: - [Portkey App](https://app.portkey.ai/) - - [API Key Management API](/api-reference/admin-api/control-plane/api-keys/create-api-key) + - [API Key Management API](/en/api-reference/admin-api/control-plane/api-keys/create-api-key) Example using Python SDK: ```python @@ -757,7 +757,7 @@ Here's a basic configuration to route requests to OpenAI, specifically using GPT ) ``` - For detailed key management instructions, see our [API Keys documentation](/api-reference/admin-api/control-plane/api-keys/create-api-key). + For detailed key management instructions, see our [API Keys documentation](/en/api-reference/admin-api/control-plane/api-keys/create-api-key). @@ -821,4 +821,4 @@ Here's a basic configuration to route requests to OpenAI, specifically using GPT

Get personalized guidance on implementing this integration

- \ No newline at end of file + diff --git a/docs/observability/weave.mdx b/docs/en/observability/weave.mdx similarity index 100% rename from docs/observability/weave.mdx rename to docs/en/observability/weave.mdx diff --git a/docs/quickstart.mdx b/docs/en/quickstart.mdx similarity index 98% rename from docs/quickstart.mdx rename to docs/en/quickstart.mdx index cf002f064..fc87c7c62 100644 --- a/docs/quickstart.mdx +++ b/docs/en/quickstart.mdx @@ -9,7 +9,7 @@ icon: rocket Let's create a simple crew that will help us `research` and `report` on the `latest AI developments` for a given topic or subject. Before we proceed, make sure you have finished installing CrewAI. -If you haven't installed them yet, you can do so by following the [installation guide](/installation). +If you haven't installed them yet, you can do so by following the [installation guide](/en/installation). Follow the steps below to get Crewing! 🚣‍♂️ @@ -182,7 +182,7 @@ Follow the steps below to get Crewing! 🚣‍♂️ Before running your crew, make sure you have the following keys set as environment variables in your `.env` file: - A [Serper.dev](https://serper.dev/) API key: `SERPER_API_KEY=YOUR_KEY_HERE` - The configuration for your choice of model, such as an API key. See the - [LLM setup guide](/concepts/llms#setting-up-your-llm) to learn how to configure models from any provider. + [LLM setup guide](/en/concepts/llms#setting-up-your-llm) to learn how to configure models from any provider. - Lock the dependencies and install them by using the CLI command: @@ -216,7 +216,7 @@ Follow the steps below to get Crewing! 🚣‍♂️ 4. Create your tasks visually and connect them in sequence 5. Configure your inputs and click "Download Code" or "Deploy" - ![Crew Studio Quickstart](../images/enterprise/crew-studio-quickstart.png) + ![Crew Studio Quickstart](/images/enterprise/crew-studio-interface.png) Start your free account at CrewAI Enterprise diff --git a/docs/snippets/snippet-intro.mdx b/docs/en/snippets/snippet-intro.mdx similarity index 100% rename from docs/snippets/snippet-intro.mdx rename to docs/en/snippets/snippet-intro.mdx diff --git a/docs/telemetry.mdx b/docs/en/telemetry.mdx similarity index 100% rename from docs/telemetry.mdx rename to docs/en/telemetry.mdx diff --git a/docs/tools/ai-ml/aimindtool.mdx b/docs/en/tools/ai-ml/aimindtool.mdx similarity index 100% rename from docs/tools/ai-ml/aimindtool.mdx rename to docs/en/tools/ai-ml/aimindtool.mdx diff --git a/docs/tools/ai-ml/codeinterpretertool.mdx b/docs/en/tools/ai-ml/codeinterpretertool.mdx similarity index 97% rename from docs/tools/ai-ml/codeinterpretertool.mdx rename to docs/en/tools/ai-ml/codeinterpretertool.mdx index 24db603d6..d89bd8b9e 100644 --- a/docs/tools/ai-ml/codeinterpretertool.mdx +++ b/docs/en/tools/ai-ml/codeinterpretertool.mdx @@ -24,8 +24,8 @@ This environment is very limited, with strict restrictions on many modules and b ### Unsafe Execution -**NOT RECOMMENDED FOR PRODUCTION** -This mode allows execution of any Python code, including dangerous calls to `sys, os..` and similar modules. [Check out](/tools/codeinterpretertool#enabling-unsafe-mode) how to enable this mode +**NOT RECOMMENDED FOR PRODUCTION** +This mode allows execution of any Python code, including dangerous calls to `sys, os..` and similar modules. [Check out](/en/tools/ai-ml/codeinterpretertool#enabling-unsafe-mode) how to enable this mode ## Logging @@ -134,8 +134,8 @@ code_interpreter = CodeInterpreterTool() data_analyst = Agent( role="Data Analyst", goal="Analyze data using Python code", - backstory="""You are an expert data analyst who specializes in using Python - to analyze and visualize data. You can write efficient code to process + backstory="""You are an expert data analyst who specializes in using Python + to analyze and visualize data. You can write efficient code to process large datasets and extract meaningful insights.""", tools=[code_interpreter], verbose=True, @@ -149,7 +149,7 @@ analysis_task = Task( 2. Calculate the correlation coefficient between x and y 3. Create a scatter plot of the data 4. Print the correlation coefficient and save the plot as 'scatter.png' - + Make sure to handle any necessary imports and print the results. """, expected_output="The correlation coefficient and confirmation that the scatter plot has been saved.", @@ -176,7 +176,7 @@ class CodeInterpreterTool(BaseTool): description: str = "Interprets Python3 code strings with a final print statement." args_schema: Type[BaseModel] = CodeInterpreterSchema default_image_tag: str = "code-interpreter:latest" - + def _run(self, **kwargs) -> str: code = kwargs.get("code", self.code) libraries_used = kwargs.get("libraries_used", []) diff --git a/docs/tools/ai-ml/dalletool.mdx b/docs/en/tools/ai-ml/dalletool.mdx similarity index 100% rename from docs/tools/ai-ml/dalletool.mdx rename to docs/en/tools/ai-ml/dalletool.mdx diff --git a/docs/tools/ai-ml/langchaintool.mdx b/docs/en/tools/ai-ml/langchaintool.mdx similarity index 100% rename from docs/tools/ai-ml/langchaintool.mdx rename to docs/en/tools/ai-ml/langchaintool.mdx diff --git a/docs/tools/ai-ml/llamaindextool.mdx b/docs/en/tools/ai-ml/llamaindextool.mdx similarity index 100% rename from docs/tools/ai-ml/llamaindextool.mdx rename to docs/en/tools/ai-ml/llamaindextool.mdx diff --git a/docs/tools/ai-ml/overview.mdx b/docs/en/tools/ai-ml/overview.mdx similarity index 71% rename from docs/tools/ai-ml/overview.mdx rename to docs/en/tools/ai-ml/overview.mdx index dc92df561..2f07dd4c2 100644 --- a/docs/tools/ai-ml/overview.mdx +++ b/docs/en/tools/ai-ml/overview.mdx @@ -9,31 +9,31 @@ These tools integrate with AI and machine learning services to enhance your agen ## **Available Tools** - + Generate AI images using OpenAI's DALL-E model. - + Process and analyze images with computer vision capabilities. - + Advanced AI reasoning and decision-making capabilities. - + Build knowledge bases and retrieval systems with LlamaIndex. - + Integrate with LangChain for complex AI workflows. - + Implement Retrieval-Augmented Generation systems. - + Execute Python code and perform data analysis. @@ -43,7 +43,7 @@ These tools integrate with AI and machine learning services to enhance your agen ## **Common Use Cases** - **Content Generation**: Create images, text, and multimedia content -- **Data Analysis**: Execute code and analyze complex datasets +- **Data Analysis**: Execute code and analyze complex datasets - **Knowledge Systems**: Build RAG systems and intelligent databases - **Computer Vision**: Process and understand visual content - **AI Safety**: Implement content moderation and safety checks @@ -61,4 +61,4 @@ agent = Agent( role="AI Specialist", tools=[image_generator, vision_processor, code_executor], goal="Create and analyze content using AI capabilities" -) \ No newline at end of file +) diff --git a/docs/tools/ai-ml/ragtool.mdx b/docs/en/tools/ai-ml/ragtool.mdx similarity index 100% rename from docs/tools/ai-ml/ragtool.mdx rename to docs/en/tools/ai-ml/ragtool.mdx diff --git a/docs/tools/ai-ml/visiontool.mdx b/docs/en/tools/ai-ml/visiontool.mdx similarity index 100% rename from docs/tools/ai-ml/visiontool.mdx rename to docs/en/tools/ai-ml/visiontool.mdx diff --git a/docs/tools/automation/apifyactorstool.mdx b/docs/en/tools/automation/apifyactorstool.mdx similarity index 100% rename from docs/tools/automation/apifyactorstool.mdx rename to docs/en/tools/automation/apifyactorstool.mdx diff --git a/docs/tools/automation/composiotool.mdx b/docs/en/tools/automation/composiotool.mdx similarity index 100% rename from docs/tools/automation/composiotool.mdx rename to docs/en/tools/automation/composiotool.mdx diff --git a/docs/tools/automation/multiontool.mdx b/docs/en/tools/automation/multiontool.mdx similarity index 100% rename from docs/tools/automation/multiontool.mdx rename to docs/en/tools/automation/multiontool.mdx diff --git a/docs/tools/automation/overview.mdx b/docs/en/tools/automation/overview.mdx similarity index 84% rename from docs/tools/automation/overview.mdx rename to docs/en/tools/automation/overview.mdx index 67434f810..a189e0639 100644 --- a/docs/tools/automation/overview.mdx +++ b/docs/en/tools/automation/overview.mdx @@ -9,15 +9,15 @@ These tools enable your agents to automate workflows, integrate with external pl ## **Available Tools** - + Run Apify actors for web scraping and automation tasks. - + Integrate with hundreds of apps and services through Composio. - + Automate browser interactions and web-based workflows. @@ -52,4 +52,4 @@ agent = Agent( - **Scalability**: Handle increased workloads automatically - **Reliability**: Consistent execution of workflows - **Connectivity**: Bridge different systems and platforms -- **Productivity**: Focus on high-value tasks while automation handles routine work \ No newline at end of file +- **Productivity**: Focus on high-value tasks while automation handles routine work diff --git a/docs/tools/cloud-storage/bedrockinvokeagenttool.mdx b/docs/en/tools/cloud-storage/bedrockinvokeagenttool.mdx similarity index 100% rename from docs/tools/cloud-storage/bedrockinvokeagenttool.mdx rename to docs/en/tools/cloud-storage/bedrockinvokeagenttool.mdx diff --git a/docs/tools/cloud-storage/bedrockkbretriever.mdx b/docs/en/tools/cloud-storage/bedrockkbretriever.mdx similarity index 100% rename from docs/tools/cloud-storage/bedrockkbretriever.mdx rename to docs/en/tools/cloud-storage/bedrockkbretriever.mdx diff --git a/docs/tools/cloud-storage/overview.mdx b/docs/en/tools/cloud-storage/overview.mdx similarity index 77% rename from docs/tools/cloud-storage/overview.mdx rename to docs/en/tools/cloud-storage/overview.mdx index 2d07168c5..57aa288af 100644 --- a/docs/tools/cloud-storage/overview.mdx +++ b/docs/en/tools/cloud-storage/overview.mdx @@ -9,19 +9,19 @@ These tools enable your agents to interact with cloud services, access cloud sto ## **Available Tools** - + Read files and data from Amazon S3 buckets. - + Write and upload files to Amazon S3 storage. - + Invoke Amazon Bedrock agents for AI-powered tasks. - + Retrieve information from Amazon Bedrock knowledge bases. @@ -47,4 +47,4 @@ agent = Agent( role="Cloud Operations Specialist", tools=[s3_reader, s3_writer, bedrock_agent], goal="Manage cloud resources and AI services" -) \ No newline at end of file +) diff --git a/docs/tools/cloud-storage/s3readertool.mdx b/docs/en/tools/cloud-storage/s3readertool.mdx similarity index 100% rename from docs/tools/cloud-storage/s3readertool.mdx rename to docs/en/tools/cloud-storage/s3readertool.mdx diff --git a/docs/tools/cloud-storage/s3writertool.mdx b/docs/en/tools/cloud-storage/s3writertool.mdx similarity index 100% rename from docs/tools/cloud-storage/s3writertool.mdx rename to docs/en/tools/cloud-storage/s3writertool.mdx diff --git a/docs/tools/database-data/mysqltool.mdx b/docs/en/tools/database-data/mysqltool.mdx similarity index 100% rename from docs/tools/database-data/mysqltool.mdx rename to docs/en/tools/database-data/mysqltool.mdx diff --git a/docs/tools/database-data/nl2sqltool.mdx b/docs/en/tools/database-data/nl2sqltool.mdx similarity index 100% rename from docs/tools/database-data/nl2sqltool.mdx rename to docs/en/tools/database-data/nl2sqltool.mdx diff --git a/docs/tools/database-data/overview.mdx b/docs/en/tools/database-data/overview.mdx similarity index 77% rename from docs/tools/database-data/overview.mdx rename to docs/en/tools/database-data/overview.mdx index 22e1ee25e..c63529790 100644 --- a/docs/tools/database-data/overview.mdx +++ b/docs/en/tools/database-data/overview.mdx @@ -9,27 +9,27 @@ These tools enable your agents to interact with various database systems, from t ## **Available Tools** - + Connect to and query MySQL databases with SQL operations. - + Search and query PostgreSQL databases efficiently. - + Access Snowflake data warehouse for analytics and reporting. - + Convert natural language queries to SQL statements automatically. - + Search vector embeddings using Qdrant vector database. - + Perform semantic search with Weaviate vector database. @@ -54,4 +54,4 @@ agent = Agent( role="Data Analyst", tools=[mysql_db, vector_search, nl_to_sql], goal="Extract insights from various data sources" -) \ No newline at end of file +) diff --git a/docs/tools/database-data/pgsearchtool.mdx b/docs/en/tools/database-data/pgsearchtool.mdx similarity index 100% rename from docs/tools/database-data/pgsearchtool.mdx rename to docs/en/tools/database-data/pgsearchtool.mdx diff --git a/docs/tools/database-data/qdrantvectorsearchtool.mdx b/docs/en/tools/database-data/qdrantvectorsearchtool.mdx similarity index 100% rename from docs/tools/database-data/qdrantvectorsearchtool.mdx rename to docs/en/tools/database-data/qdrantvectorsearchtool.mdx diff --git a/docs/tools/database-data/snowflakesearchtool.mdx b/docs/en/tools/database-data/snowflakesearchtool.mdx similarity index 100% rename from docs/tools/database-data/snowflakesearchtool.mdx rename to docs/en/tools/database-data/snowflakesearchtool.mdx diff --git a/docs/tools/database-data/weaviatevectorsearchtool.mdx b/docs/en/tools/database-data/weaviatevectorsearchtool.mdx similarity index 100% rename from docs/tools/database-data/weaviatevectorsearchtool.mdx rename to docs/en/tools/database-data/weaviatevectorsearchtool.mdx diff --git a/docs/tools/file-document/csvsearchtool.mdx b/docs/en/tools/file-document/csvsearchtool.mdx similarity index 100% rename from docs/tools/file-document/csvsearchtool.mdx rename to docs/en/tools/file-document/csvsearchtool.mdx diff --git a/docs/tools/file-document/directoryreadtool.mdx b/docs/en/tools/file-document/directoryreadtool.mdx similarity index 100% rename from docs/tools/file-document/directoryreadtool.mdx rename to docs/en/tools/file-document/directoryreadtool.mdx diff --git a/docs/tools/file-document/directorysearchtool.mdx b/docs/en/tools/file-document/directorysearchtool.mdx similarity index 100% rename from docs/tools/file-document/directorysearchtool.mdx rename to docs/en/tools/file-document/directorysearchtool.mdx diff --git a/docs/tools/file-document/docxsearchtool.mdx b/docs/en/tools/file-document/docxsearchtool.mdx similarity index 100% rename from docs/tools/file-document/docxsearchtool.mdx rename to docs/en/tools/file-document/docxsearchtool.mdx diff --git a/docs/tools/file-document/filereadtool.mdx b/docs/en/tools/file-document/filereadtool.mdx similarity index 100% rename from docs/tools/file-document/filereadtool.mdx rename to docs/en/tools/file-document/filereadtool.mdx diff --git a/docs/tools/file-document/filewritetool.mdx b/docs/en/tools/file-document/filewritetool.mdx similarity index 100% rename from docs/tools/file-document/filewritetool.mdx rename to docs/en/tools/file-document/filewritetool.mdx diff --git a/docs/tools/file-document/jsonsearchtool.mdx b/docs/en/tools/file-document/jsonsearchtool.mdx similarity index 100% rename from docs/tools/file-document/jsonsearchtool.mdx rename to docs/en/tools/file-document/jsonsearchtool.mdx diff --git a/docs/tools/file-document/mdxsearchtool.mdx b/docs/en/tools/file-document/mdxsearchtool.mdx similarity index 100% rename from docs/tools/file-document/mdxsearchtool.mdx rename to docs/en/tools/file-document/mdxsearchtool.mdx diff --git a/docs/tools/file-document/overview.mdx b/docs/en/tools/file-document/overview.mdx similarity index 70% rename from docs/tools/file-document/overview.mdx rename to docs/en/tools/file-document/overview.mdx index dc92b9f78..b0053b1ca 100644 --- a/docs/tools/file-document/overview.mdx +++ b/docs/en/tools/file-document/overview.mdx @@ -9,47 +9,47 @@ These tools enable your agents to work with various file formats and document ty ## **Available Tools** - + Read content from any file type including text, markdown, and more. - + Write content to files, create new documents, and save processed data. - + Search and extract text content from PDF documents efficiently. - + Search through Microsoft Word documents and extract relevant content. - + Parse and search through JSON files with advanced query capabilities. - + Process and search through CSV files, extract specific rows and columns. - + Parse XML files and search for specific elements and attributes. - + Search through MDX files and extract content from documentation. - + Search through plain text files with pattern matching capabilities. - + Search for files and folders within directory structures. - + Read and list directory contents, file structures, and metadata. @@ -57,7 +57,7 @@ These tools enable your agents to work with various file formats and document ty ## **Common Use Cases** - **Document Processing**: Extract and analyze content from various file formats -- **Data Import**: Read structured data from CSV, JSON, and XML files +- **Data Import**: Read structured data from CSV, JSON, and XML files - **Content Search**: Find specific information within large document collections - **File Management**: Organize and manipulate files and directories - **Data Export**: Save processed results to various file formats @@ -85,4 +85,4 @@ agent = Agent( - **File Permissions**: Ensure your agent has proper read/write permissions - **Large Files**: Consider chunking for very large documents - **Format Support**: Check tool documentation for supported file formats -- **Error Handling**: Implement proper error handling for corrupted or inaccessible files \ No newline at end of file +- **Error Handling**: Implement proper error handling for corrupted or inaccessible files diff --git a/docs/tools/file-document/pdfsearchtool.mdx b/docs/en/tools/file-document/pdfsearchtool.mdx similarity index 100% rename from docs/tools/file-document/pdfsearchtool.mdx rename to docs/en/tools/file-document/pdfsearchtool.mdx diff --git a/docs/tools/file-document/txtsearchtool.mdx b/docs/en/tools/file-document/txtsearchtool.mdx similarity index 100% rename from docs/tools/file-document/txtsearchtool.mdx rename to docs/en/tools/file-document/txtsearchtool.mdx diff --git a/docs/tools/file-document/xmlsearchtool.mdx b/docs/en/tools/file-document/xmlsearchtool.mdx similarity index 100% rename from docs/tools/file-document/xmlsearchtool.mdx rename to docs/en/tools/file-document/xmlsearchtool.mdx diff --git a/docs/tools/overview.mdx b/docs/en/tools/overview.mdx similarity index 64% rename from docs/tools/overview.mdx rename to docs/en/tools/overview.mdx index 4ce7d7827..8d69017bb 100644 --- a/docs/tools/overview.mdx +++ b/docs/en/tools/overview.mdx @@ -9,64 +9,64 @@ CrewAI provides an extensive library of pre-built tools to enhance your agents' ## **Tool Categories** - Read, write, and search through various file formats including PDF, DOCX, JSON, CSV, and more. Perfect for document processing workflows. - Extract data from websites, automate browser interactions, and scrape content at scale with tools like Firecrawl, Selenium, and more. - Perform web searches, find code repositories, research YouTube content, and discover information across the internet. - Connect to SQL databases, vector stores, and data warehouses. Query MySQL, PostgreSQL, Snowflake, Qdrant, and Weaviate. - Generate images with DALL-E, process vision tasks, integrate with LangChain, build RAG systems, and leverage code interpreters. - Interact with cloud services including AWS S3, Amazon Bedrock, and other cloud storage and AI services. - Automate workflows with Apify, Composio, and other integration platforms to connect your agents with external services. @@ -78,22 +78,22 @@ CrewAI provides an extensive library of pre-built tools to enhance your agents' Need a specific tool? Here are some popular choices: - + Implement Retrieval-Augmented Generation - + Google search API - + Read any file type - + Extract web content - + Execute Python code - + Access AWS S3 files @@ -103,7 +103,7 @@ Need a specific tool? Here are some popular choices: To use any tool in your CrewAI project: 1. **Import** the tool in your crew configuration -2. **Add** it to your agent's tools list +2. **Add** it to your agent's tools list 3. **Configure** any required API keys or settings ```python @@ -117,4 +117,4 @@ agent = Agent( ) ``` -Ready to explore? Pick a category above to discover tools that fit your use case! \ No newline at end of file +Ready to explore? Pick a category above to discover tools that fit your use case! diff --git a/docs/tools/search-research/bravesearchtool.mdx b/docs/en/tools/search-research/bravesearchtool.mdx similarity index 100% rename from docs/tools/search-research/bravesearchtool.mdx rename to docs/en/tools/search-research/bravesearchtool.mdx diff --git a/docs/tools/search-research/codedocssearchtool.mdx b/docs/en/tools/search-research/codedocssearchtool.mdx similarity index 100% rename from docs/tools/search-research/codedocssearchtool.mdx rename to docs/en/tools/search-research/codedocssearchtool.mdx diff --git a/docs/tools/search-research/exasearchtool.mdx b/docs/en/tools/search-research/exasearchtool.mdx similarity index 100% rename from docs/tools/search-research/exasearchtool.mdx rename to docs/en/tools/search-research/exasearchtool.mdx diff --git a/docs/tools/search-research/githubsearchtool.mdx b/docs/en/tools/search-research/githubsearchtool.mdx similarity index 100% rename from docs/tools/search-research/githubsearchtool.mdx rename to docs/en/tools/search-research/githubsearchtool.mdx diff --git a/docs/tools/search-research/linkupsearchtool.mdx b/docs/en/tools/search-research/linkupsearchtool.mdx similarity index 100% rename from docs/tools/search-research/linkupsearchtool.mdx rename to docs/en/tools/search-research/linkupsearchtool.mdx diff --git a/docs/tools/search-research/overview.mdx b/docs/en/tools/search-research/overview.mdx similarity index 64% rename from docs/tools/search-research/overview.mdx rename to docs/en/tools/search-research/overview.mdx index 693ad3845..7b28032cf 100644 --- a/docs/tools/search-research/overview.mdx +++ b/docs/en/tools/search-research/overview.mdx @@ -9,39 +9,39 @@ These tools enable your agents to search the web, research topics, and find info ## **Available Tools** - + Google search API integration for comprehensive web search capabilities. - + Privacy-focused search with Brave's independent search index. - + AI-powered search for finding specific and relevant content. - + Real-time web search with fresh content indexing. - + Search GitHub repositories, code, issues, and documentation. - + Search within specific websites and domains. - + Search through code documentation and technical resources. - + Search YouTube channels for specific content and creators. - + Find and analyze YouTube videos by topic, keyword, or criteria. @@ -59,7 +59,7 @@ from crewai_tools import SerperDevTool, GitHubSearchTool, YoutubeVideoSearchTool # Create research tools web_search = SerperDevTool() -code_search = GitHubSearchTool() +code_search = GitHubSearchTool() video_research = YoutubeVideoSearchTool() # Add to your agent @@ -68,4 +68,4 @@ agent = Agent( tools=[web_search, code_search, video_research], goal="Gather comprehensive information on any topic" ) -``` \ No newline at end of file +``` diff --git a/docs/tools/search-research/serperdevtool.mdx b/docs/en/tools/search-research/serperdevtool.mdx similarity index 100% rename from docs/tools/search-research/serperdevtool.mdx rename to docs/en/tools/search-research/serperdevtool.mdx diff --git a/docs/tools/search-research/websitesearchtool.mdx b/docs/en/tools/search-research/websitesearchtool.mdx similarity index 100% rename from docs/tools/search-research/websitesearchtool.mdx rename to docs/en/tools/search-research/websitesearchtool.mdx diff --git a/docs/tools/search-research/youtubechannelsearchtool.mdx b/docs/en/tools/search-research/youtubechannelsearchtool.mdx similarity index 100% rename from docs/tools/search-research/youtubechannelsearchtool.mdx rename to docs/en/tools/search-research/youtubechannelsearchtool.mdx diff --git a/docs/tools/search-research/youtubevideosearchtool.mdx b/docs/en/tools/search-research/youtubevideosearchtool.mdx similarity index 100% rename from docs/tools/search-research/youtubevideosearchtool.mdx rename to docs/en/tools/search-research/youtubevideosearchtool.mdx diff --git a/docs/tools/web-scraping/browserbaseloadtool.mdx b/docs/en/tools/web-scraping/browserbaseloadtool.mdx similarity index 100% rename from docs/tools/web-scraping/browserbaseloadtool.mdx rename to docs/en/tools/web-scraping/browserbaseloadtool.mdx diff --git a/docs/tools/web-scraping/firecrawlcrawlwebsitetool.mdx b/docs/en/tools/web-scraping/firecrawlcrawlwebsitetool.mdx similarity index 100% rename from docs/tools/web-scraping/firecrawlcrawlwebsitetool.mdx rename to docs/en/tools/web-scraping/firecrawlcrawlwebsitetool.mdx diff --git a/docs/tools/web-scraping/firecrawlscrapewebsitetool.mdx b/docs/en/tools/web-scraping/firecrawlscrapewebsitetool.mdx similarity index 100% rename from docs/tools/web-scraping/firecrawlscrapewebsitetool.mdx rename to docs/en/tools/web-scraping/firecrawlscrapewebsitetool.mdx diff --git a/docs/tools/web-scraping/firecrawlsearchtool.mdx b/docs/en/tools/web-scraping/firecrawlsearchtool.mdx similarity index 100% rename from docs/tools/web-scraping/firecrawlsearchtool.mdx rename to docs/en/tools/web-scraping/firecrawlsearchtool.mdx diff --git a/docs/tools/web-scraping/hyperbrowserloadtool.mdx b/docs/en/tools/web-scraping/hyperbrowserloadtool.mdx similarity index 100% rename from docs/tools/web-scraping/hyperbrowserloadtool.mdx rename to docs/en/tools/web-scraping/hyperbrowserloadtool.mdx diff --git a/docs/tools/web-scraping/overview.mdx b/docs/en/tools/web-scraping/overview.mdx similarity index 74% rename from docs/tools/web-scraping/overview.mdx rename to docs/en/tools/web-scraping/overview.mdx index e44aba4ba..85ab01b5f 100644 --- a/docs/tools/web-scraping/overview.mdx +++ b/docs/en/tools/web-scraping/overview.mdx @@ -9,55 +9,55 @@ These tools enable your agents to interact with the web, extract data from websi ## **Available Tools** - + General-purpose web scraping tool for extracting content from any website. - + Target specific elements on web pages with precision scraping capabilities. - + Crawl entire websites systematically with Firecrawl's powerful engine. - + High-performance web scraping with Firecrawl's advanced capabilities. - + Search and extract specific content using Firecrawl's search features. - + Browser automation and scraping with Selenium WebDriver capabilities. - + Professional web scraping with ScrapFly's premium scraping service. - + Graph-based web scraping for complex data relationships. - + Comprehensive web crawling and data extraction capabilities. - + Cloud-based browser automation with BrowserBase infrastructure. - + Fast browser interactions with HyperBrowser's optimized engine. - + Intelligent browser automation with natural language commands. - + Access web data at scale with Oxylabs. diff --git a/docs/tools/web-scraping/oxylabsscraperstool.mdx b/docs/en/tools/web-scraping/oxylabsscraperstool.mdx similarity index 100% rename from docs/tools/web-scraping/oxylabsscraperstool.mdx rename to docs/en/tools/web-scraping/oxylabsscraperstool.mdx diff --git a/docs/tools/web-scraping/scrapeelementfromwebsitetool.mdx b/docs/en/tools/web-scraping/scrapeelementfromwebsitetool.mdx similarity index 100% rename from docs/tools/web-scraping/scrapeelementfromwebsitetool.mdx rename to docs/en/tools/web-scraping/scrapeelementfromwebsitetool.mdx diff --git a/docs/tools/web-scraping/scrapegraphscrapetool.mdx b/docs/en/tools/web-scraping/scrapegraphscrapetool.mdx similarity index 100% rename from docs/tools/web-scraping/scrapegraphscrapetool.mdx rename to docs/en/tools/web-scraping/scrapegraphscrapetool.mdx diff --git a/docs/tools/web-scraping/scrapewebsitetool.mdx b/docs/en/tools/web-scraping/scrapewebsitetool.mdx similarity index 100% rename from docs/tools/web-scraping/scrapewebsitetool.mdx rename to docs/en/tools/web-scraping/scrapewebsitetool.mdx diff --git a/docs/tools/web-scraping/scrapflyscrapetool.mdx b/docs/en/tools/web-scraping/scrapflyscrapetool.mdx similarity index 100% rename from docs/tools/web-scraping/scrapflyscrapetool.mdx rename to docs/en/tools/web-scraping/scrapflyscrapetool.mdx diff --git a/docs/tools/web-scraping/seleniumscrapingtool.mdx b/docs/en/tools/web-scraping/seleniumscrapingtool.mdx similarity index 100% rename from docs/tools/web-scraping/seleniumscrapingtool.mdx rename to docs/en/tools/web-scraping/seleniumscrapingtool.mdx diff --git a/docs/tools/web-scraping/spidertool.mdx b/docs/en/tools/web-scraping/spidertool.mdx similarity index 100% rename from docs/tools/web-scraping/spidertool.mdx rename to docs/en/tools/web-scraping/spidertool.mdx diff --git a/docs/tools/web-scraping/stagehandtool.mdx b/docs/en/tools/web-scraping/stagehandtool.mdx similarity index 100% rename from docs/tools/web-scraping/stagehandtool.mdx rename to docs/en/tools/web-scraping/stagehandtool.mdx diff --git a/docs/pt-BR/api-reference/introduction.mdx b/docs/pt-BR/api-reference/introduction.mdx new file mode 100644 index 000000000..77725da57 --- /dev/null +++ b/docs/pt-BR/api-reference/introduction.mdx @@ -0,0 +1,119 @@ +--- +title: "Introdução" +description: "Referência completa para a API REST do CrewAI Enterprise" +icon: "code" +--- + +# CrewAI Enterprise API + +Bem-vindo à referência da API do CrewAI Enterprise. Esta API permite que você interaja programaticamente com seus crews implantados, possibilitando a integração com seus aplicativos, fluxos de trabalho e serviços. + +## Início Rápido + + + + Navegue até a página de detalhes do seu crew no painel do CrewAI Enterprise e copie seu Bearer Token na aba Status. + + + + Use o endpoint `GET /inputs` para ver quais parâmetros seu crew espera. + + + + Chame `POST /kickoff` com seus inputs para iniciar a execução do crew e receber um `kickoff_id`. + + + + Use `GET /status/{kickoff_id}` para checar o status da execução e recuperar os resultados. + + + +## 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 | + + +Você pode encontrar ambos os tipos de token na aba Status da página de detalhes do seu crew no painel do CrewAI Enterprise. + + +## 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 + + +**Por que não há botão "Enviar"?** Como cada usuário do CrewAI Enterprise possui sua própria URL de crew, utilizamos o **modo referência** em vez de um playground interativo para evitar confusão. Isso mostra exatamente como as requisições devem ser feitas, sem botões de envio não funcionais. + + +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:** + + + + Copie os exemplos cURL e substitua a URL + token por seus valores reais + + + Importe os exemplos na sua ferramenta de testes de API preferida + + + +**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? + + + + Obtenha ajuda com integração da API e resolução de problemas + + + Gerencie seus crews e visualize logs de execução + + \ No newline at end of file diff --git a/docs/pt-BR/changelog.mdx b/docs/pt-BR/changelog.mdx new file mode 100644 index 000000000..722d696a7 --- /dev/null +++ b/docs/pt-BR/changelog.mdx @@ -0,0 +1,473 @@ +--- +title: Registro de Alterações +description: Veja as atualizações e mudanças mais recentes do CrewAI +icon: timeline +--- + + + ## Destaques da Versão + + + + + + + **Melhorias & Correções no Núcleo** + - Corrigido erro de codificação ao criar ferramentas + - Corrigido teste do llama com falha + - Configuração de logs atualizada para mais consistência + - Inicialização e tratamento de eventos de telemetria aprimorados + + **Novas Funcionalidades & Aprimoramentos** + - Adicionado **atributo markdown** à classe Task + - Adicionado **atributo reasoning** à classe Agent + - Adicionada flag **inject_date** ao Agent para injeção automática de data + - Implementado **HallucinationGuardrail** (sem-operação, com cobertura de testes) + + **Documentação & Guias** + - Documentação adicionada para **StagehandTool** e melhoria na estrutura MDX + - Inclusa documentação para integração **MCP** e atualização nos docs corporativos + - Eventos de conhecimento documentados e documentação de reasoning atualizada + - Adicionada explicação do parâmetro stop + - Corrigidas referências de import nos exemplos de documentação (before_kickoff, after_kickoff) + - Atualizações gerais e reestruturação nos docs para maior clareza + + + + ## Destaques da Versão + + + + + + + **Melhorias & Correções no Núcleo** + - Corrigida **interpolação com hífens** + + + + ## Destaques da Versão + + + + + + + **Melhorias & Correções no Núcleo** + - Conjunto completo de regras do Ruff habilitado por padrão para linting mais rigoroso + - Corrigida condição de corrida no FilteredStream usando context managers + - Corrigido problema de reset de conhecimento do agente + - Lógica de busca de agente refatorada para módulo utilitário + + **Novas Funcionalidades & Aprimoramentos** + - Suporte adicionado para **carregar um Agent diretamente de um repositório** + - Permitida configuração de contexto vazio em Task + - Feedback do repositório de Agent aprimorado e correção no comportamento de auto-import de Tool + - Inicialização direta de conhecimento introduzida (bypassando knowledge_sources) + + **Documentação & Guias** + - security.md atualizado para refletir práticas atuais de segurança + - Seção de configuração do Google revisada para mais clareza + - Adicionado link para AI Studio ao inserir chave Gemini + - Guia de observabilidade do Arize Phoenix atualizado + - Documentação de fluxo renovada + + + + ## Destaques da Versão + + + + + + + **Melhorias & Correções no Núcleo** + - Confiabilidade de testes aprimorada melhorando o tratamento do pytest para testes instáveis + - Corrigido crash no reset de memória por incompatibilidade de dimensões de embeddings + - Identificação do fluxo pai habilitada para Crew e LiteAgent + - Crashes de telemetria prevenidos quando indisponíveis + - Atualização da versão do **LiteLLM** para melhor compatibilidade + - Corrigidos testes do conversor de llama removendo skip_external_api + + **Novas Funcionalidades & Aprimoramentos** + - Introduzida **reescrita de prompt de recuperação de conhecimento** no Agent para melhor rastreamento e debug + - Guias de configuração do LLM e início rápido tornados independentes do modelo + + **Documentação & Guias** + - Adicionada documentação de configuração avançada para o RAG tool + - Guia de resolução de problemas no Windows atualizado + - Exemplos na documentação refinados para maior clareza + - Correção de erros ortográficos em docs e arquivos de configuração + + + + ## Destaques da Versão + + + + + + + **Melhorias & Correções no Núcleo** + - Corrigidos problemas com prompt ou templates de sistema ausentes + - Removida configuração global de logs para evitar sobreposição não intencional + - Renomeado **TaskGuardrail para LLMGuardrail** para maior clareza + - Versão do litellm rebaixada para 1.167.1 visando compatibilidade + - Adicionados arquivos init.py ausentes para garantir inicialização correta dos módulos + + **Novas Funcionalidades & Aprimoramentos** + - Suporte adicionado para **criação de Guardrails sem código** facilitando o controle de comportamento da IA + + **Documentação & Guias** + - CrewStructuredTool removido da documentação pública para refletir uso interno + - Documentação corporativa e embed do YouTube atualizados para melhor onboarding + + + + ## Destaques da Versão + + + + + + + **Novas Funcionalidades & Aprimoramentos** + - Adicionado suporte ao parâmetro `result_as_answer` no decorator `@tool`. + - Suporte a novos modelos de linguagem: GPT-4.1, Gemini-2.0 e Gemini-2.5 Pro. + - Capacidades de gerenciamento de conhecimento aprimoradas. + - Adicionado provedor Huggingface na CLI. + - Compatibilidade e suporte CI melhorados para Python 3.10+. + + **Melhorias & Correções no Núcleo** + - Corrigidos problemas com parâmetros de template incorretos e entradas ausentes. + - Fluxo assíncrono aprimorado com verificações de condição coroutine. + - Gerenciamento de memória aprimorado com configuração isolada e cópia correta dos objetos. + - Inicialização de lite agents corrigida com referências corretas. + - Corrigidos problemas de type hint em Python e remoção de imports redundantes. + - Atualização do posicionamento de eventos para rastreamento do uso de ferramentas. + - Exceções explícitas lançadas quando fluxos falham. + - Remoção de código e comentários redundantes em diversos módulos. + - Atualização da ação de token do GitHub App para v2. + + **Documentação & Guias** + - Estrutura documental aprimorada, incluindo instruções para implantação corporativa. + - Criação automática de pastas de saída para geração de documentação. + - Link quebrado reparado na documentação do WeaviateVectorSearchTool. + - Correções na documentação do guardrail e nos caminhos de import dos search tools para JSON. + - Atualização na documentação do CodeInterpreterTool. + - Aprimoramento de SEO, navegação contextual e tratamento de erros nas páginas de documentação. + + + + ## Destaques da Versão + + + + + + + **Melhorias & Correções no Núcleo** + - Versão do **crewai-tools** atualizada para a mais recente + - Versão do **liteLLM** atualizada para a mais recente + - Correção no **Mem0 OSS** + + + + ## Destaques da Versão + + + + + + + **Novas Funcionalidades & Aprimoramentos** + - Agents como unidade atômica. (`Agent(...).kickoff()`) + - Suporte para [implementações Custom LLM](https://docs.crewai.com/guides/advanced/custom-llm). + - Memória externa integrada e [Opik observability](https://docs.crewai.com/how-to/opik-observability). + - Extração de YAML aprimorada. + - Validação multimodal de agentes. + - Impressões digitais seguras adicionadas para agents e crews. + + **Melhorias & Correções no Núcleo** + - Serialização, cópia de agent e compatibilidade Python aprimoradas. + - Suporte a curingas adicionado a `emit()` + - Suporte a chamadas adicionais do roteador e ajustes de janela de contexto. + - Correções em typing, validação e imports. + - Melhoria na performance de métodos. + - Manipulação de tasks do agent, emissão de eventos e gerenciamento de memória aprimorados. + - Correções na CLI, tarefas condicionais, comportamento de clonagem e saídas de ferramentas. + + **Documentação & Guias** + - Estrutura, tema e organização da documentação aprimorados. + - Guias para Local NVIDIA NIM com WSL2, W&B Weave e Arize Phoenix adicionados. + - Exemplos de configuração de ferramentas, prompts e docs de observabilidade atualizados. + - Guia para usar agentes singulares nos Flows. + + + + ## Destaques da Versão + + + + + + + **Novas Funcionalidades & Aprimoramentos** + - Conversão de tabs para espaços no template `crew.py` + - Streaming de respostas LLM e sistema de eventos aprimorados + - Inclusão de `model_name` + - Event Listener aprimorado com visualização rica e logs melhorados + - Impressões digitais adicionadas + + **Correções de Bugs** + - Correções de problemas com Mistral + - Correção de bug na documentação + - Correção de erro de type check na propriedade fingerprint + + **Atualizações em Documentação** + - Documentação de ferramentas aprimorada + - Guia de instalação atualizado para o pacote `uv` tool + - Instruções adicionadas para upgrade do crewAI com o `uv` tool + - Documentação para `ApifyActorsTool` incluída + + + + ## Destaques da Versão + + + + + + + **Melhorias & Correções no Núcleo** + - Correção de variáveis de template ausentes e configuração de memória de usuário + - Suporte a fluxo assíncrono melhorado e resolução para formatação de respostas do agente + - Função de reset de memória aprimorada e correção nos comandos de memória da CLI + - Correções em tipos, propriedades de chamadas de ferramenta e desacoplamento de telemetria + + **Novas Funcionalidades & Aprimoramentos** + - Exportação de estado do Flow e utilitários de estado melhorados + - Configuração de conhecimento do agente aprimorada com embedder opcional para crew + - Emissor de eventos adicionado para melhor observabilidade e rastreamento de chamadas LLM + - Suporte para Python 3.10 e ChatOllama via langchain_ollama + - Suporte ao tamanho da janela de contexto para o modelo o3-mini + - Adicionada capacidade de múltiplas chamadas de roteador + + **Documentação & Guias** + - Layout e estrutura hierárquica da documentação aprimorados + - Guia para QdrantVectorSearchTool incluído e uso de event listener esclarecido + - Correções de erros nos prompts e atualização da lista de modelos do Amazon Bedrock + + + + ## Destaques da Versão + + + + + + + **Melhorias & Correções no Núcleo** + - Suporte LLM expandido: melhorar saída estruturada do LLM, manuseio de parâmetros e formatação para modelos Anthropic + - Estabilidade de Crew & Agent: corrigido clonagem de agents/crews com knowledge sources, múltiplas saídas de task em tarefas condicionais e callbacks de tarefa de Crew ignorados + - Correções de Memória & Armazenamento: melhora no gerenciamento de memória de curto prazo com Bedrock, inicialização correta do embedder e função reset memories adicionada na classe crew + - Confiabilidade em Treinamento & Execução: corrigidos treinamento quebrado e questões de interpolação com tipos de entrada dict e list + + **Novas Funcionalidades & Aprimoramentos** + - Gerenciamento Avançado de Conhecimento: convencionamento de nomes melhorado e configuração de embedding aprimorada com suporte a embedder customizado + - Logging & Observabilidade Expandidos: suporte ao formato JSON para logging e documentação de rastreamento no MLflow integrada + - Melhorias no Tratamento de Dados: atualização do excel_knowledge_source.py para processar arquivos com múltipl abas + - Desempenho Geral & Limpeza do Código: alinhamento de código corporativo e resolução de problemas de linting + - Novo tool adicionado: `QdrantVectorSearchTool` + + **Documentação & Guias** + - Docs de AI & Memória atualizados: melhorias em documentação do Bedrock, Google AI e memória de longo prazo + - Clareza em tarefas & fluxos: adicionada linha "Entrada Humana" em Task Attributes, guia para Langfuse e documentação para FileWriterTool + - Diversas correções de ortografia & formatação + + + + ## Destaques da Versão + + + + + + + **Funcionalidades** + - Adição dos docs Composio + - Adicionado SageMaker como provedor LLM + + **Correções** + - Correção geral nas conexões LLM + - Uso de acessores seguros no treinamento + - Checagem de versão adicionada ao crew_chat.py + + **Documentação** + - Novos docs para crewai chat + - Melhorias no formato e clareza nos docs da CLI e da Composio Tool + + + + ## Destaques da Versão + + + + + + + **Funcionalidades** + - Conversation crew v1 + - Adição de ID único para estados de flow + - Adição do decorator @persist com a interface FlowPersistence + + **Integrações** + - Integração SambaNova adicionada + - Novo provedor NVIDIA NIM na CLI + - Apresentando VoyageAI + + **Correções** + - Correção de comportamento de chave API e tratamento de entidades na integração com Mem0 + - Correção na lógica de invoke principal e nos testes relacionados + - Inputs de ferramentas agora são objetos reais em vez de strings + - Partes importantes adicionadas no processo de criação de ferramentas + - Versão do litellm foi rebaixada para prevenir problema no Windows + - Correção antes da execução caso inputs estejam nulos + - Corrigidos erros, modelo pydantic aninhado e falhas de docling + + + + ## Destaques da Versão + + + + + + + **Novas Funcionalidades** + - Adição de habilidades multimodais ao Crew + - Guardrails programáticos + - HITL com múltiplas rodadas + - Suporte ao Gemini 2.0 + - Melhorias em CrewAI Flows + - Permissões de workflow adicionadas + - Suporte a langfuse com litellm + - Integração Portkey com CrewAI + - Método interpolate_only e melhorias em tratamento de erros + - Suporte ao Docling + - Suporte ao Weviate + + **Correções** + - output_file não respeitava caminho do sistema + - Erro de I/O em disco ao resetar memória de curto prazo + - CrewJSONEncoder agora aceita enums + - Versão máxima do Python + - Interpolação de output_file em Task + - Manipulação adequada de nomes de funções coworker quanto a caixa e espaços + - tiktoken adicionado como dependência explícita e documentação do requisito Rust + - Inclusão do conhecimento do agent no processo de planejamento + - Inicialização do armazenamento definida como None em KnowledgeStorage + - Verificações opcionais de armazenamento corrigidas + - Emissor de eventos incluído nos flows + - Melhorias em docstring, tratamento de erros e type hints + - Suppressão de userWarnings de problemas pydantic no litellm + + + + ## Destaques da Versão + + + + + + **Alterações** + - Removidas todas referências a pipeline e roteador de pipeline + - Adicionado Nvidia NIM como provedor em Custom LLM + - Adicionado demo de knowledge + melhorias nos docs de knowledge + - Adicionado suporte a múltiplas rodadas de HITL + - Novos docs sobre crew em yaml com decorators + - Template de crew simplificado + + + + ## Destaques da Versão + + + + + + **Funcionalidades** + - Adicionado conhecimento em nível de agent + - Feat/remover langchain + - Aprimoradas saídas tipadas das tasks + - Login no Tool Repository ao fazer login no crewai + + **Correções** + - Correção em issues de result as answer não encerrando loop do LLM corretamente + - Correção de ausência de nome de chave ao rodar com o provedor ollama + - Correção em erro ortográfico identificado + + **Documentação** + - Atualização no readme para rodar mypy + - Adição do conhecimento em mint.json + - Atualização das ações do Github + - Atualização na documentação de Agents para incluir duas abordagens na criação de agent + - Melhorias na Configuração e Uso do LLM + + + + **Novas Funcionalidades** + - Novos callbacks before_kickoff e after_kickoff em crew + - Suporte para pre-seed de agents com Knowledge + - Adicionado suporte para recuperação de preferências de usuário e memórias usando Mem0 + + **Correções** + - Correção em execução assíncrona + - Upgrade do chroma e ajuste no gerador de funções do embedder + - Atualização do CLI Watson com modelos suportados + docs + - Redução do nível para Bandit + - Correção de todos os testes + + **Documentação** + - Documentação atualizada + + + + **Correções** + - Correção em bug de substituição do callback Tokens + - Correção em issue de callback Step + - Informação de prompt tokens em cache adicionada nas métricas de uso + - Correção no teste crew_train_success + \ No newline at end of file diff --git a/docs/pt-BR/concepts/agents.mdx b/docs/pt-BR/concepts/agents.mdx new file mode 100644 index 000000000..0bfdc69ac --- /dev/null +++ b/docs/pt-BR/concepts/agents.mdx @@ -0,0 +1,593 @@ +--- +title: Agentes +description: Guia detalhado sobre como criar e gerenciar agentes no framework CrewAI. +icon: robot +--- + +## Visão Geral de um Agente + +No framework CrewAI, um `Agent` é uma unidade autônoma que pode: +- Executar tarefas específicas +- Tomar decisões com base em seu papel e objetivo +- Utilizar ferramentas para alcançar objetivos +- Comunicar e colaborar com outros agentes +- Manter a memória de interações +- Delegar tarefas, quando permitido + + +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. + + + +O CrewAI Enterprise inclui um Construtor Visual de Agentes, que simplifica a criação e configuração de agentes sem escrever código. Projete seus agentes visualmente e teste-os em tempo real. + +![Visual Agent Builder Screenshot](/images/enterprise/crew-studio-interface.png) + +O Construtor Visual de Agentes permite: +- Configuração intuitiva de agentes com interfaces baseadas em formulários +- Testes e validação em tempo real +- Biblioteca de modelos com tipos de agentes pré-configurados +- Fácil personalização de atributos e comportamentos do agente + + +## Atributos do Agente + +| Atributo | Parâmetro | Tipo | Descrição | +| :-------------------------------------- | :----------------------- | :---------------------------- | :----------------------------------------------------------------------------------------------------------------- | +| **Role (Função)** | `role` | `str` | Define a função e a área de especialização do agente dentro da equipe. | +| **Goal (Objetivo)** | `goal` | `str` | O objetivo individual que guia a tomada de decisão do agente. | +| **Backstory (História de fundo)** | `backstory` | `str` | Fornece contexto e personalidade ao agente, enriquecendo as interações. | +| **LLM** _(opcional)_ | `llm` | `Union[str, LLM, Any]` | Modelo de linguagem que alimenta o agente. Padrão: modelo especificado em `OPENAI_MODEL_NAME` ou "gpt-4". | +| **Tools (Ferramentas)** _(opcional)_ | `tools` | `List[BaseTool]` | Capacidades ou funções disponíveis para o agente. Padrão: lista vazia. | +| **Function Calling LLM** _(opcional)_ | `function_calling_llm` | `Optional[Any]` | Modelo de linguagem usado para chamada de ferramentas, sobrescreve LLM principal se especificado. | +| **Max Iterations** _(opcional)_ | `max_iter` | `int` | Número máximo de iterações antes do agente fornecer sua melhor resposta. Padrão: 20. | +| **Max RPM** _(opcional)_ | `max_rpm` | `Optional[int]` | Quantidade máxima de requisições por minuto para evitar limites de taxa. | +| **Max Execution Time** _(opcional)_ | `max_execution_time` | `Optional[int]` | Tempo máximo (em segundos) de execução da tarefa. | +| **Verbose** _(opcional)_ | `verbose` | `bool` | Habilita logs detalhados de execução para depuração. Padrão: False. | +| **Allow Delegation** _(opcional)_ | `allow_delegation` | `bool` | Permite que o agente delegue tarefas para outros agentes. Padrão: False. | +| **Step Callback** _(opcional)_ | `step_callback` | `Optional[Any]` | Função chamada após cada passo do agente, sobrescreve callback da equipe. | +| **Cache** _(opcional)_ | `cache` | `bool` | Ativa cache para o uso de ferramentas. Padrão: True. | +| **System Template** _(opcional)_ | `system_template` | `Optional[str]` | Template personalizado de prompt de sistema para o agente. | +| **Prompt Template** _(opcional)_ | `prompt_template` | `Optional[str]` | Template de prompt personalizado para o agente. | +| **Response Template** _(opcional)_ | `response_template` | `Optional[str]` | Template de resposta personalizado para o agente. | +| **Allow Code Execution** _(opcional)_ | `allow_code_execution` | `Optional[bool]` | Ativa execução de código pelo agente. Padrão: False. | +| **Max Retry Limit** _(opcional)_ | `max_retry_limit` | `int` | Número máximo de tentativas (retries) em caso de erro. Padrão: 2. | +| **Respect Context Window** _(opcional)_ | `respect_context_window` | `bool` | Mantém as mensagens dentro do tamanho da janela de contexto, resumindo quando necessário. Padrão: True. | +| **Code Execution Mode** _(opcional)_ | `code_execution_mode` | `Literal["safe", "unsafe"]` | Modo de execução de código: 'safe' (usando Docker) ou 'unsafe' (direto). Padrão: 'safe'. | +| **Multimodal** _(opcional)_ | `multimodal` | `bool` | Se o agente suporta capacidades multimodais. Padrão: False. | +| **Inject Date** _(opcional)_ | `inject_date` | `bool` | Se deve injetar automaticamente a data atual nas tarefas. Padrão: False. | +| **Date Format** _(opcional)_ | `date_format` | `str` | Formato de data utilizado quando `inject_date` está ativo. Padrão: "%Y-%m-%d" (formato ISO). | +| **Reasoning** _(opcional)_ | `reasoning` | `bool` | Se o agente deve refletir e criar um plano antes de executar uma tarefa. Padrão: False. | +| **Max Reasoning Attempts** _(opcional)_ | `max_reasoning_attempts` | `Optional[int]` | Número máximo de tentativas de raciocínio antes de executar a tarefa. Se None, tentará até estar pronto. | +| **Embedder** _(opcional)_ | `embedder` | `Optional[Dict[str, Any]]` | Configuração do embedder utilizado pelo agente. | +| **Knowledge Sources** _(opcional)_ | `knowledge_sources` | `Optional[List[BaseKnowledgeSource]]` | Fontes de conhecimento disponíveis para o agente. | +| **Use System Prompt** _(opcional)_ | `use_system_prompt` | `Optional[bool]` | Se deve usar o system prompt (suporte para modelo o1). Padrão: True. | + +## Criando Agentes + +Existem duas maneiras de criar agentes no CrewAI: usando **configuração YAML (recomendado)** ou definindo-os **diretamente em código**. + +### Configuração em YAML (Recomendado) + +Usar configuração em YAML proporciona uma maneira mais limpa e fácil de manter para definir agentes. Recomendamos fortemente esse método em seus projetos CrewAI. + +Depois de criar seu projeto CrewAI conforme descrito na seção de [Instalação](/pt-BR/installation), navegue até o arquivo `src/latest_ai_development/config/agents.yaml` e edite o template para atender aos seus requisitos. + + +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'}) +``` + + +Veja um exemplo de como configurar agentes usando YAML: + +```yaml agents.yaml +# src/latest_ai_development/config/agents.yaml +researcher: + role: > + {topic} Senior Data Researcher + goal: > + Uncover cutting-edge developments in {topic} + backstory: > + You're a seasoned researcher with a knack for uncovering the latest + developments in {topic}. Known for your ability to find the most relevant + information and present it in a clear and concise manner. + +reporting_analyst: + role: > + {topic} Reporting Analyst + goal: > + Create detailed reports based on {topic} data analysis and research findings + backstory: > + You're a meticulous analyst with a keen eye for detail. You're known for + your ability to turn complex data into clear and concise reports, making + it easy for others to understand and act on the information you provide. +``` + +Para usar essa configuração YAML no seu código, crie uma classe de crew que herda de `CrewBase`: + +```python Code +# src/latest_ai_development/crew.py +from crewai import Agent, Crew, Process +from crewai.project import CrewBase, agent, crew +from crewai_tools import SerperDevTool + +@CrewBase +class LatestAiDevelopmentCrew(): + """LatestAiDevelopment crew""" + + agents_config = "config/agents.yaml" + + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], # type: ignore[index] + verbose=True, + tools=[SerperDevTool()] + ) + + @agent + def reporting_analyst(self) -> Agent: + return Agent( + config=self.agents_config['reporting_analyst'], # type: ignore[index] + verbose=True + ) +``` + + +Os nomes utilizados em seus arquivos YAML (`agents.yaml`) devem ser iguais aos nomes dos métodos no seu código Python. + + +### Definição Direta em Código + +Você pode criar agentes diretamente em código instanciando a classe `Agent`. Veja um exemplo abrangente mostrando todos os parâmetros disponíveis: + +```python Code +from crewai import Agent +from crewai_tools import SerperDevTool + +# Crie um agente com todos os parâmetros disponíveis +agent = Agent( + role="Senior Data Scientist", + goal="Analyze and interpret complex datasets to provide actionable insights", + backstory="With over 10 years of experience in data science and machine learning, " + "you excel at finding patterns in complex datasets.", + llm="gpt-4", # Default: OPENAI_MODEL_NAME or "gpt-4" + function_calling_llm=None, # Optional: Separate LLM for tool calling + verbose=False, # Default: False + allow_delegation=False, # Default: False + max_iter=20, # Default: 20 iterations + max_rpm=None, # Optional: Rate limit for API calls + max_execution_time=None, # Optional: Maximum execution time in seconds + max_retry_limit=2, # Default: 2 retries on error + allow_code_execution=False, # Default: False + code_execution_mode="safe", # Default: "safe" (options: "safe", "unsafe") + respect_context_window=True, # Default: True + use_system_prompt=True, # Default: True + multimodal=False, # Default: False + inject_date=False, # Default: False + date_format="%Y-%m-%d", # Default: ISO format + reasoning=False, # Default: False + max_reasoning_attempts=None, # Default: None + tools=[SerperDevTool()], # Optional: List of tools + knowledge_sources=None, # Optional: List of knowledge sources + embedder=None, # Optional: Custom embedder configuration + system_template=None, # Optional: Custom system prompt template + prompt_template=None, # Optional: Custom prompt template + response_template=None, # Optional: Custom response template + step_callback=None, # Optional: Callback function for monitoring +) +``` + +Vamos detalhar algumas combinações de parâmetros-chave para casos de uso comuns: + +#### Agente de Pesquisa Básico +```python Code +research_agent = Agent( + role="Research Analyst", + goal="Find and summarize information about specific topics", + backstory="You are an experienced researcher with attention to detail", + tools=[SerperDevTool()], + verbose=True # Enable logging for debugging +) +``` + +#### Agente de Desenvolvimento de Código +```python Code +dev_agent = Agent( + role="Senior Python Developer", + goal="Write and debug Python code", + backstory="Expert Python developer with 10 years of experience", + allow_code_execution=True, + code_execution_mode="safe", # Uses Docker for safety + max_execution_time=300, # 5-minute timeout + max_retry_limit=3 # More retries for complex code tasks +) +``` + +#### Agente de Análise de Longa Duração +```python Code +analysis_agent = Agent( + role="Data Analyst", + goal="Perform deep analysis of large datasets", + backstory="Specialized in big data analysis and pattern recognition", + memory=True, + respect_context_window=True, + max_rpm=10, # Limit API calls + function_calling_llm="gpt-4o-mini" # Cheaper model for tool calls +) +``` + +#### Agente com Template Personalizado +```python Code +custom_agent = Agent( + role="Customer Service Representative", + goal="Assist customers with their inquiries", + backstory="Experienced in customer support with a focus on satisfaction", + system_template="""<|start_header_id|>system<|end_header_id|> + {{ .System }}<|eot_id|>""", + prompt_template="""<|start_header_id|>user<|end_header_id|> + {{ .Prompt }}<|eot_id|>""", + response_template="""<|start_header_id|>assistant<|end_header_id|> + {{ .Response }}<|eot_id|>""", +) +``` + +#### Agente Ciente de Data, com Raciocínio +```python Code +strategic_agent = Agent( + role="Market Analyst", + goal="Track market movements with precise date references and strategic planning", + backstory="Expert in time-sensitive financial analysis and strategic reporting", + inject_date=True, # Automatically inject current date into tasks + date_format="%B %d, %Y", # Format as "May 21, 2025" + reasoning=True, # Enable strategic planning + max_reasoning_attempts=2, # Limit planning iterations + verbose=True +) +``` + +#### Agente de Raciocínio +```python Code +reasoning_agent = Agent( + role="Strategic Planner", + goal="Analyze complex problems and create detailed execution plans", + backstory="Expert strategic planner who methodically breaks down complex challenges", + reasoning=True, # Enable reasoning and planning + max_reasoning_attempts=3, # Limit reasoning attempts + max_iter=30, # Allow more iterations for complex planning + verbose=True +) +``` + +#### Agente Multimodal +```python Code +multimodal_agent = Agent( + role="Visual Content Analyst", + goal="Analyze and process both text and visual content", + backstory="Specialized in multimodal analysis combining text and image understanding", + multimodal=True, # Enable multimodal capabilities + verbose=True +) +``` + +### Detalhes dos Parâmetros + +#### Parâmetros Críticos +- `role`, `goal` e `backstory` são obrigatórios e definem o comportamento do agente +- `llm` determina o modelo de linguagem utilizado (padrão: GPT-4 da OpenAI) + +#### Memória e Contexto +- `memory`: Ative para manter o histórico de conversas +- `respect_context_window`: Evita problemas com limites de tokens +- `knowledge_sources`: Adicione bases de conhecimento específicas do domínio + +#### Controle de Execução +- `max_iter`: Número máximo de tentativas antes da melhor resposta +- `max_execution_time`: Tempo limite em segundos +- `max_rpm`: Limite de requisições por minuto +- `max_retry_limit`: Tentativas de correção em erros + +#### Execução de Código +- `allow_code_execution`: Deve ser True para permitir execução de código +- `code_execution_mode`: + - `"safe"`: Usa Docker (recomendado para produção) + - `"unsafe"`: Execução direta (apenas em ambientes confiáveis) + + + Isso executa uma imagem Docker padrão. Se você deseja configurar a imagem Docker, veja a ferramenta Code Interpreter na seção de ferramentas. + Adicione a ferramenta de interpretação de código como um parâmetro em ferramentas no agente. + + +#### 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 + + +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. + + + +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. + + +## Ferramentas do Agente + +Agentes podem ser equipados com diversas ferramentas para ampliar suas capacidades. O CrewAI suporta ferramentas do: +- [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools) +- [LangChain Tools](https://python.langchain.com/docs/integrations/tools) + +Veja como adicionar ferramentas a um agente: + +```python Code +from crewai import Agent +from crewai_tools import SerperDevTool, WikipediaTools + +# Criar ferramentas +search_tool = SerperDevTool() +wiki_tool = WikipediaTools() + +# Adicionar ferramentas ao agente +researcher = Agent( + role="AI Technology Researcher", + goal="Research the latest AI developments", + tools=[search_tool, wiki_tool], + verbose=True +) +``` + +## Memória e Contexto do Agente + +Agentes podem manter a memória de suas interações e usar contexto de tarefas anteriores. Isto é especialmente útil para fluxos de trabalho complexos onde é necessário reter informações ao longo de várias tarefas. + +```python Code +from crewai import Agent + +analyst = Agent( + role="Data Analyst", + goal="Analyze and remember complex data patterns", + memory=True, # Enable memory + verbose=True +) +``` + + +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. + + +## Gerenciamento da Janela de Contexto + +O CrewAI inclui um gerenciamento automático sofisticado de janela de contexto para lidar com situações onde as conversas excedem o limite de tokens do modelo de linguagem. Esse poderoso recurso é controlado pelo parâmetro `respect_context_window`. + +### Como Funciona o Gerenciamento de Janela de Contexto + +Quando o histórico de conversas de um agente se torna muito grande para a janela de contexto do LLM, o CrewAI detecta essa situação automaticamente e pode: + +1. **Resumir o conteúdo automaticamente** (com `respect_context_window=True`) +2. **Parar a execução com erro** (com `respect_context_window=False`) + +### Manipulação Automática de Contexto (`respect_context_window=True`) + +Esta é a **configuração padrão e recomendada** para a maioria dos casos. Quando ativada, CrewAI irá: + +```python Code +# Agente com gerenciamento automático de contexto (padrão) +smart_agent = Agent( + role="Research Analyst", + goal="Analyze large documents and datasets", + backstory="Expert at processing extensive information", + respect_context_window=True, # 🔑 Default: auto-handle context limits + verbose=True +) +``` + +**O que acontece quando os limites de contexto são excedidos:** +- ⚠️ **Mensagem de aviso**: `"Context length exceeded. Summarizing content to fit the model context window."` +- 🔄 **Resumir automaticamente**: O CrewAI resume o histórico da conversa de forma inteligente +- ✅ **Execução contínua**: A execução da tarefa prossegue normalmente com o contexto resumido +- 📝 **Informação preservada**: Informações-chave são mantidas enquanto reduz a contagem de tokens + +### Limites Estritos de Contexto (`respect_context_window=False`) + +Quando você precisa de controle total e prefere que a execução pare a perder qualquer informação: + +```python Code +# Agente com limites estritos de contexto +strict_agent = Agent( + role="Legal Document Reviewer", + goal="Provide precise legal analysis without information loss", + backstory="Legal expert requiring complete context for accurate analysis", + respect_context_window=False, # ❌ Stop execution on context limit + verbose=True +) +``` + +**O que acontece quando os limites de contexto são excedidos:** +- ❌ **Mensagem de erro**: `"Context length exceeded. Consider using smaller text or RAG tools from crewai_tools."` +- 🛑 **Execução interrompida**: A execução da tarefa é parada imediatamente +- 🔧 **Intervenção manual necessária**: Você precisará modificar sua abordagem + +### Como Escolher a Melhor Configuração + +#### Use `respect_context_window=True` (padrão) quando: +- **Processar documentos grandes** que podem ultrapassar os limites de contexto +- **Conversas longas** onde certo grau de resumo é aceitável +- **Tarefas de pesquisa** onde o contexto geral é mais importante que detalhes exatos +- **Prototipagem e desenvolvimento** quando se deseja execução robusta + +```python Code +# Ideal para processamento de documentos +document_processor = Agent( + role="Document Analyst", + goal="Extract insights from large research papers", + backstory="Expert at analyzing extensive documentation", + respect_context_window=True, # Lida com documentos grandes sem problemas + max_iter=50, # Permite mais iterações para análises complexas + verbose=True +) +``` + +#### Use `respect_context_window=False` quando: +- **Precisão é crítica** e perda de informação é inaceitável +- **Tarefas jurídicas ou médicas** que requerem contexto completo +- **Revisão de código** onde detalhes perdidos podem causar bugs +- **Análise financeira** onde precisão é fundamental + +```python Code +# Ideal para tarefas de precisão +precision_agent = Agent( + role="Code Security Auditor", + goal="Identify security vulnerabilities in code", + backstory="Security expert requiring complete code context", + respect_context_window=False, # Prefere falhar do que análise incompleta + max_retry_limit=1, # Falha rápida em caso de problemas de contexto + verbose=True +) +``` + +### Abordagens Alternativas para Grandes Volumes de Dados + +Ao lidar com conjuntos de dados muito grandes, considere as seguintes estratégias: + +#### 1. Use Ferramentas RAG +```python Code +from crewai_tools import RagTool + +# Crie uma ferramenta RAG para processamento de documentos grandes +rag_tool = RagTool() + +rag_agent = Agent( + role="Research Assistant", + goal="Query large knowledge bases efficiently", + backstory="Expert at using RAG tools for information retrieval", + tools=[rag_tool], # Usar RAG ao invés de grandes janelas de contexto + respect_context_window=True, + verbose=True +) +``` + +#### 2. Use Fontes de Conhecimento +```python Code +# Use fontes de conhecimento ao invés de prompts grandes +knowledge_agent = Agent( + role="Knowledge Expert", + goal="Answer questions using curated knowledge", + backstory="Expert at leveraging structured knowledge sources", + knowledge_sources=[your_knowledge_sources], # Conhecimento pré-processado + respect_context_window=True, + verbose=True +) +``` + +### Boas Práticas para Janela de Contexto + +1. **Monitore o uso de contexto**: Ative `verbose=True` para visualizar o gerenciamento de contexto em ação +2. **Otimize para eficiência**: Estruture tarefas para minimizar o acúmulo de contexto +3. **Use modelos apropriados**: Escolha LLMs com janelas de contexto adequadas à sua tarefa +4. **Teste ambos os modos**: Experimente `True` e `False` para descobrir o que funciona melhor para seu caso +5. **Combine com RAG**: Utilize ferramentas RAG para grandes conjuntos de dados ao invés de depender apenas da janela de contexto + +### Solucionando Problemas de Contexto + +**Se você receber erros de limite de contexto:** +```python Code +# Solução rápida: Habilite manipulação automática +agent.respect_context_window = True + +# Solução melhor: Use ferramentas RAG para dados volumosos +from crewai_tools import RagTool +agent.tools = [RagTool()] + +# Alternativa: Divida as tarefas em partes menores +# Ou use fontes de conhecimento no lugar de prompts extensos +``` + +**Se o resumo automático perder informações importantes:** +```python Code +# Desative o resumo automático e use RAG +agent = Agent( + role="Detailed Analyst", + goal="Maintain complete information accuracy", + backstory="Expert requiring full context", + respect_context_window=False, # Sem resumo automático + tools=[RagTool()], # Use RAG para grandes volumes de dados + verbose=True +) +``` + + +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! + + +## Considerações e Boas Práticas Importantes + +### Segurança e Execução de Código +- Ao usar `allow_code_execution`, seja cauteloso com entradas do usuário e sempre as valide +- Use `code_execution_mode: "safe"` (Docker) em ambientes de produção +- Considere definir limites adequados de `max_execution_time` para evitar loops infinitos + +### Otimização de Performance +- Use `respect_context_window: true` para evitar problemas com limite de tokens +- Ajuste `max_rpm` para evitar rate limiting +- Ative `cache: true` para melhorar performance em tarefas repetitivas +- Ajuste `max_iter` e `max_retry_limit` conforme a complexidade da tarefa + +### Gerenciamento de Memória e Contexto +- Considere `knowledge_sources` para informações específicas de domínio +- Configure `embedder` ao usar modelos de embedding personalizados +- Use templates personalizados (`system_template`, `prompt_template`, `response_template`) para controle fino do comportamento do agente + +### Funcionalidades Avançadas +- Ative `reasoning: true` para agentes que precisam planejar e refletir antes de tarefas complexas +- Defina `max_reasoning_attempts` para controlar as iterações de planejamento (`None` para ilimitadas) +- Use `inject_date: true` para dar consciência temporal a agentes em tarefas que dependem de datas +- Personalize o formato de data com `date_format` usando códigos padrões do Python datetime +- Ative `multimodal: true` para agentes que precisam processar texto e imagem + +### Colaboração entre Agentes +- Ative `allow_delegation: true` quando agentes precisarem trabalhar juntos +- Use `step_callback` para monitorar e registrar interações dos agentes +- Considere usar LLMs diferentes para propósitos distintos: + - `llm` principal para raciocínio complexo + - `function_calling_llm` para uso eficiente de ferramentas + +### Consciência de Data e Raciocínio +- Use `inject_date: true` para fornecer consciência temporal aos agentes em tarefas sensíveis ao tempo +- Customize o formato de data com `date_format` usando códigos standards de datetime do Python +- Códigos válidos incluem: %Y (ano), %m (mês), %d (dia), %B (nome completo do mês), etc. +- Formatos de data inválidos serão registrados como avisos e não modificarão a descrição da tarefa +- Ative `reasoning: true` para tarefas complexas que se beneficiam de planejamento e reflexão antecipados + +### Compatibilidade de Modelos +- Defina `use_system_prompt: false` para modelos antigos que não suportam mensagens de sistema +- Certifique-se que o `llm` escolhido suporta as funcionalidades necessárias (como function calling) + +## Solução de Problemas Comuns + +1. **Limite de Taxa (Rate Limiting)**: Se atingir limites de API: + - Implemente o `max_rpm` adequado + - Use cache para operações repetitivas + - Considere agrupar requisições em lote + +2. **Erros de Janela de Contexto**: Se exceder limites de contexto: + - Habilite `respect_context_window` + - Otimize seus prompts + - Limpe periodicamente a memória do agente + +3. **Problemas de Execução de Código**: Se a execução de código falhar: + - Verifique se o Docker está instalado para o modo seguro + - Cheque permissões de execução + - Revise as configurações do sandbox de código + +4. **Problemas de Memória**: Se as respostas do agente parecerem inconsistentes: + - Cheque a configuração das fontes de conhecimento + - Analise o gerenciamento do histórico de conversas + +Lembre-se de que agentes são mais eficientes quando configurados de acordo com o caso de uso específico. Reserve um tempo para entender seus requisitos e ajustar esses parâmetros conforme necessário. diff --git a/docs/pt-BR/concepts/cli.mdx b/docs/pt-BR/concepts/cli.mdx new file mode 100644 index 000000000..af5c10872 --- /dev/null +++ b/docs/pt-BR/concepts/cli.mdx @@ -0,0 +1,312 @@ +--- +title: CLI +description: Aprenda a usar o CLI do CrewAI para interagir com o CrewAI. +icon: terminal +--- + +## Visão Geral + +O CLI do CrewAI fornece um conjunto de comandos para interagir com o CrewAI, permitindo que você crie, treine, execute e gerencie crews & flows. + +## Instalação + +Para usar o CLI do CrewAI, certifique-se de que o CrewAI está instalado: + +```shell Terminal +pip install crewai +``` + +## Uso Básico + +A estrutura básica de um comando CLI do CrewAI é: + +```shell Terminal +crewai [COMMAND] [OPTIONS] [ARGUMENTS] +``` + +## Comandos Disponíveis + +### 1. Create + +Crie um novo crew ou flow. + +```shell Terminal +crewai create [OPTIONS] TYPE NAME +``` + +- `TYPE`: Escolha entre "crew" ou "flow" +- `NAME`: Nome do crew ou flow + +Exemplo: +```shell Terminal +crewai create crew my_new_crew +crewai create flow my_new_flow +``` + +### 2. Version + +Mostre a versão instalada do CrewAI. + +```shell Terminal +crewai version [OPTIONS] +``` + +- `--tools`: (Opcional) Mostra a versão instalada das ferramentas do CrewAI + +Exemplo: +```shell Terminal +crewai version +crewai version --tools +``` + +### 3. Train + +Treine o crew por um número específico de iterações. + +```shell Terminal +crewai train [OPTIONS] +``` + +- `-n, --n_iterations INTEGER`: Número de iterações para treinar o crew (padrão: 5) +- `-f, --filename TEXT`: Caminho para um arquivo customizado para treinamento (padrão: "trained_agents_data.pkl") + +Exemplo: +```shell Terminal +crewai train -n 10 -f my_training_data.pkl +``` + +### 4. Replay + +Reexecute a execução do crew a partir de uma tarefa específica. + +```shell Terminal +crewai replay [OPTIONS] +``` + +- `-t, --task_id TEXT`: Reexecuta o crew a partir deste task ID, incluindo todas as tarefas subsequentes + +Exemplo: +```shell Terminal +crewai replay -t task_123456 +``` + +### 5. Log-tasks-outputs + +Recupere as saídas mais recentes das tarefas crew.kickoff() do seu crew. + +```shell Terminal +crewai log-tasks-outputs +``` + +### 6. Reset-memories + +Redefine as memórias do crew (longa, curta, de entidades, latest_crew_kickoff_outputs). + +```shell Terminal +crewai reset-memories [OPTIONS] +``` + +- `-l, --long`: Redefine a memória de LONGO PRAZO +- `-s, --short`: Redefine a memória de CURTO PRAZO +- `-e, --entities`: Redefine a memória de ENTIDADES +- `-k, --kickoff-outputs`: Redefine as OUTPUTS DA TAREFA KICKOFF MAIS RECENTE +- `-kn, --knowledge`: Redefine o armazenamento de CONHECIMENTO +- `-akn, --agent-knowledge`: Redefine o armazenamento de CONHECIMENTO DOS AGENTES +- `-a, --all`: Redefine TODAS as memórias + +Exemplo: +```shell Terminal +crewai reset-memories --long --short +crewai reset-memories --all +``` + +### 7. Test + +Teste o crew e avalie os resultados. + +```shell Terminal +crewai test [OPTIONS] +``` + +- `-n, --n_iterations INTEGER`: Número de iterações para testar o crew (padrão: 3) +- `-m, --model TEXT`: Modelo LLM para executar os testes no Crew (padrão: "gpt-4o-mini") + +Exemplo: +```shell Terminal +crewai test -n 5 -m gpt-3.5-turbo +``` + +### 8. Run + +Execute o crew ou flow. + +```shell Terminal +crewai run +``` + + +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. + + + +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. + + +### 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 +``` + +Garanta que você execute estes comandos a partir do diretório raiz do seu projeto CrewAI. + + +IMPORTANTE: Defina a propriedade `chat_llm` no seu arquivo `crew.py` para habilitar este comando. + +```python +@crew +def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + chat_llm="gpt-4o", # LLM para orquestração de chat + ) +``` + + +### 10. Deploy + +Implemente o crew ou flow no [CrewAI Enterprise](https://app.crewai.com). + +- **Autenticação**: Você precisa estar autenticado para implementar no CrewAI Enterprise. + ```shell Terminal + crewai signup + ``` + Caso já tenha uma conta, você pode fazer login com: + ```shell Terminal + crewai login + ``` + +- **Criar um deployment**: Depois de autenticado, você pode criar um deployment para seu crew ou flow a partir da raiz do seu projeto local. + ```shell Terminal + crewai deploy create + ``` + - Lê a configuração do seu projeto local. + - Solicita a confirmação das variáveis de ambiente (como `OPENAI_API_KEY`, `SERPER_API_KEY`) encontradas localmente. Elas serão armazenadas de forma segura junto ao deployment na plataforma Enterprise. Verifique se suas chaves sensíveis estão corretamente configuradas localmente (por exemplo, em um arquivo `.env`) antes de executar este comando. + +### 11. Gerenciamento de Organização + +Gerencie suas organizações no CrewAI Enterprise. + +```shell Terminal +crewai org [COMMAND] [OPTIONS] +``` + +#### Comandos: + +- `list`: Liste todas as organizações das quais você faz parte +```shell Terminal +crewai org list +``` + +- `current`: Exibe sua organização ativa atualmente +```shell Terminal +crewai org current +``` + +- `switch`: Mude para uma organização específica +```shell Terminal +crewai org switch +``` + + +Você deve estar autenticado no CrewAI Enterprise para usar estes comandos de gerenciamento de organização. + + +- **Criar um deployment** (continuação): + - Vincula o deployment ao respectivo repositório remoto do GitHub (normalmente detectado automaticamente). + +- **Implantar o Crew**: Depois de autenticado, você pode implantar seu crew ou flow no CrewAI Enterprise. + ```shell Terminal + crewai deploy push + ``` + - Inicia o processo de deployment na plataforma CrewAI Enterprise. + - Após a iniciação bem-sucedida, será exibida a mensagem Deployment created successfully! juntamente com o Nome do Deployment e um Deployment ID (UUID) único. + +- **Status do Deployment**: Você pode verificar o status do seu deployment com: + ```shell Terminal + crewai deploy status + ``` + Isso retorna o status mais recente do último deployment iniciado (por exemplo, `Building Images for Crew`, `Deploy Enqueued`, `Online`). + +- **Logs do Deployment**: Você pode checar os logs do seu deployment com: + ```shell Terminal + crewai deploy logs + ``` + Isso faz o streaming dos logs do deployment para seu terminal. + +- **Listar deployments**: Você pode listar todos os seus deployments com: + ```shell Terminal + crewai deploy list + ``` + Isto lista todos os seus deployments. + +- **Deletar um deployment**: Você pode deletar um deployment com: + ```shell Terminal + crewai deploy remove + ``` + Isto exclui o deployment da plataforma CrewAI Enterprise. + +- **Comando de Ajuda**: Você pode obter ajuda sobre o CLI com: + ```shell Terminal + crewai deploy --help + ``` + Isto exibe a mensagem de ajuda para o CLI CrewAI Deploy. + +Assista ao vídeo tutorial para uma demonstração passo-a-passo de implantação do seu crew no [CrewAI Enterprise](http://app.crewai.com) usando o CLI. + + + +### 11. Chaves de API + +Ao executar o comando ```crewai create crew```, o CLI primeiro mostrará os 5 provedores de LLM mais comuns e pedirá para você selecionar um. + +Após selecionar um provedor de LLM, será solicitado que você informe as chaves de API. + +#### Provedores iniciais de chave de API + +Inicialmente, o CLI solicitará as chaves de API para os seguintes serviços: + +* OpenAI +* Groq +* Anthropic +* Google Gemini +* SambaNova + +Ao selecionar um provedor, o CLI solicitará que você insira sua chave de API. + +#### Outras opções + +Se você selecionar a opção 6, será possível escolher de uma lista de provedores suportados pelo LiteLLM. + +Ao escolher um provedor, o CLI solicitará que você informe o nome da chave e a chave de API. + +Veja o seguinte link para o nome de chave de cada provedor: + +* [LiteLLM Providers](https://docs.litellm.ai/docs/providers) \ No newline at end of file diff --git a/docs/pt-BR/concepts/collaboration.mdx b/docs/pt-BR/concepts/collaboration.mdx new file mode 100644 index 000000000..b5d0481c8 --- /dev/null +++ b/docs/pt-BR/concepts/collaboration.mdx @@ -0,0 +1,362 @@ +--- +title: Colaboração +description: Como permitir que agentes trabalhem juntos, deleguem tarefas e se comuniquem de forma eficaz em equipes CrewAI. +icon: screen-users +--- + +## Visão Geral + +A colaboração no CrewAI permite que agentes trabalhem juntos como uma equipe, delegando tarefas e fazendo perguntas para aproveitar a expertise uns dos outros. Quando `allow_delegation=True`, os agentes automaticamente têm acesso a poderosas ferramentas de colaboração. + +## Guia Rápido: Habilite a Colaboração + +```python +from crewai import Agent, Crew, Task + +# Enable collaboration for agents +researcher = Agent( + role="Research Specialist", + goal="Conduct thorough research on any topic", + backstory="Expert researcher with access to various sources", + allow_delegation=True, # 🔑 Key setting for collaboration + verbose=True +) + +writer = Agent( + role="Content Writer", + goal="Create engaging content based on research", + backstory="Skilled writer who transforms research into compelling content", + allow_delegation=True, # 🔑 Enables asking questions to other agents + verbose=True +) + +# Agents can now collaborate automatically +crew = Crew( + agents=[researcher, writer], + tasks=[...], + verbose=True +) +``` + +## Como Funciona a Colaboração entre Agentes + +Quando `allow_delegation=True`, o CrewAI automaticamente fornece aos agentes duas ferramentas poderosas: + +### 1. **Ferramenta de Delegação de Trabalho** +Permite que agentes designem tarefas para colegas com expertise específica. + +```python +# Agent automatically gets this tool: +# Delegate work to coworker(task: str, context: str, coworker: str) +``` + +### 2. **Ferramenta de Fazer Pergunta** +Permite que agentes façam perguntas específicas para obter informações de colegas. + +```python +# Agent automatically gets this tool: +# Ask question to coworker(question: str, context: str, coworker: str) +``` + +## Colaboração em Ação + +Veja um exemplo completo onde agentes colaboram em uma tarefa de criação de conteúdo: + +```python +from crewai import Agent, Crew, Task, Process + +# Create collaborative agents +researcher = Agent( + role="Research Specialist", + goal="Find accurate, up-to-date information on any topic", + backstory="""You're a meticulous researcher with expertise in finding + reliable sources and fact-checking information across various domains.""", + allow_delegation=True, + verbose=True +) + +writer = Agent( + role="Content Writer", + goal="Create engaging, well-structured content", + backstory="""You're a skilled content writer who excels at transforming + research into compelling, readable content for different audiences.""", + allow_delegation=True, + verbose=True +) + +editor = Agent( + role="Content Editor", + goal="Ensure content quality and consistency", + backstory="""You're an experienced editor with an eye for detail, + ensuring content meets high standards for clarity and accuracy.""", + allow_delegation=True, + verbose=True +) + +# Create a task that encourages collaboration +article_task = Task( + description="""Write a comprehensive 1000-word article about 'The Future of AI in Healthcare'. + + The article should include: + - Current AI applications in healthcare + - Emerging trends and technologies + - Potential challenges and ethical considerations + - Expert predictions for the next 5 years + + Collaborate with your teammates to ensure accuracy and quality.""", + expected_output="A well-researched, engaging 1000-word article with proper structure and citations", + agent=writer # Writer leads, but can delegate research to researcher +) + +# Create collaborative crew +crew = Crew( + agents=[researcher, writer, editor], + tasks=[article_task], + process=Process.sequential, + verbose=True +) + +result = crew.kickoff() +``` + +## Padrões de Colaboração + +### Padrão 1: Pesquisa → Redação → Edição +```python +research_task = Task( + description="Research the latest developments in quantum computing", + expected_output="Comprehensive research summary with key findings and sources", + agent=researcher +) + +writing_task = Task( + description="Write an article based on the research findings", + expected_output="Engaging 800-word article about quantum computing", + agent=writer, + context=[research_task] # Gets research output as context +) + +editing_task = Task( + description="Edit and polish the article for publication", + expected_output="Publication-ready article with improved clarity and flow", + agent=editor, + context=[writing_task] # Gets article draft as context +) +``` + +### Padrão 2: Tarefa Única Colaborativa +```python +collaborative_task = Task( + description="""Create a marketing strategy for a new AI product. + + Writer: Focus on messaging and content strategy + Researcher: Provide market analysis and competitor insights + + Work together to create a comprehensive strategy.""", + expected_output="Complete marketing strategy with research backing", + agent=writer # Lead agent, but can delegate to researcher +) +``` + +## Colaboração Hierárquica + +Para projetos complexos, utilize um processo hierárquico com um agente gerente: + +```python +from crewai import Agent, Crew, Task, Process + +# Manager agent coordinates the team +manager = Agent( + role="Project Manager", + goal="Coordinate team efforts and ensure project success", + backstory="Experienced project manager skilled at delegation and quality control", + allow_delegation=True, + verbose=True +) + +# Specialist agents +researcher = Agent( + role="Researcher", + goal="Provide accurate research and analysis", + backstory="Expert researcher with deep analytical skills", + allow_delegation=False, # Specialists focus on their expertise + verbose=True +) + +writer = Agent( + role="Writer", + goal="Create compelling content", + backstory="Skilled writer who creates engaging content", + allow_delegation=False, + verbose=True +) + +# Manager-led task +project_task = Task( + description="Create a comprehensive market analysis report with recommendations", + expected_output="Executive summary, detailed analysis, and strategic recommendations", + agent=manager # Manager will delegate to specialists +) + +# Hierarchical crew +crew = Crew( + agents=[manager, researcher, writer], + tasks=[project_task], + process=Process.hierarchical, # Manager coordinates everything + manager_llm="gpt-4o", # Specify LLM for manager + verbose=True +) +``` + +## Melhores Práticas para Colaboração + +### 1. **Definição Clara de Papéis** +```python +# ✅ Bom: papéis específicos e complementares +researcher = Agent(role="Market Research Analyst", ...) +writer = Agent(role="Technical Content Writer", ...) + +# ❌ Evite: Papéis sobrepostos ou vagos +agent1 = Agent(role="General Assistant", ...) +agent2 = Agent(role="Helper", ...) +``` + +### 2. **Delegação Estratégica Habilitada** +```python +# ✅ Habilite delegação para coordenadores e generalistas +lead_agent = Agent( + role="Content Lead", + allow_delegation=True, # Can delegate to specialists + ... +) + +# ✅ Desative para especialistas focados (opcional) +specialist_agent = Agent( + role="Data Analyst", + allow_delegation=False, # Focuses on core expertise + ... +) +``` + +### 3. **Compartilhamento de Contexto** +```python +# ✅ Use o parâmetro context para dependências entre tarefas +writing_task = Task( + description="Write article based on research", + agent=writer, + context=[research_task], # Shares research results + ... +) +``` + +### 4. **Descrições Claras de Tarefas** +```python +# ✅ Descrições específicas e acionáveis +Task( + description="""Research competitors in the AI chatbot space. + Focus on: pricing models, key features, target markets. + Provide data in a structured format.""", + ... +) + +# ❌ Descrições vagas que não orientam a colaboração +Task(description="Do some research about chatbots", ...) +``` + +## Solução de Problemas em Colaboração + +### Problema: Agentes Não Colaboram +**Sintomas:** Agentes trabalham isoladamente, sem ocorrer delegação +```python +# ✅ Solução: Certifique-se que a delegação está habilitada +agent = Agent( + role="...", + allow_delegation=True, # This is required! + ... +) +``` + +### Problema: Troca Excessiva de Perguntas +**Sintomas:** Agentes fazem perguntas em excesso, progresso lento +```python +# ✅ Solução: Forneça melhor contexto e papéis específicos +Task( + description="""Write a technical blog post about machine learning. + + Context: Target audience is software developers with basic ML knowledge. + Length: 1200 words + Include: code examples, practical applications, best practices + + If you need specific technical details, delegate research to the researcher.""", + ... +) +``` + +### Problema: Loops de Delegação +**Sintomas:** Agentes delegam tarefas repetidamente uns para os outros indefinidamente +```python +# ✅ Solução: Hierarquia e responsabilidades bem definidas +manager = Agent(role="Manager", allow_delegation=True) +specialist1 = Agent(role="Specialist A", allow_delegation=False) # No re-delegation +specialist2 = Agent(role="Specialist B", allow_delegation=False) +``` + +## Recursos Avançados de Colaboração + +### Regras Personalizadas de Colaboração +```python +# Set specific collaboration guidelines in agent backstory +agent = Agent( + role="Senior Developer", + backstory="""You lead development projects and coordinate with team members. + + Collaboration guidelines: + - Delegate research tasks to the Research Analyst + - Ask the Designer for UI/UX guidance + - Consult the QA Engineer for testing strategies + - Only escalate blocking issues to the Project Manager""", + allow_delegation=True +) +``` + +### Monitoramento da Colaboração +```python +def track_collaboration(output): + """Track collaboration patterns""" + if "Delegate work to coworker" in output.raw: + print("🤝 Delegation occurred") + if "Ask question to coworker" in output.raw: + print("❓ Question asked") + +crew = Crew( + agents=[...], + tasks=[...], + step_callback=track_collaboration, # Monitor collaboration + verbose=True +) +``` + +## Memória e Aprendizado + +Permita que agentes se lembrem de colaborações passadas: + +```python +agent = Agent( + role="Content Lead", + memory=True, # Remembers past interactions + allow_delegation=True, + verbose=True +) +``` + +Com a memória ativada, os agentes aprendem com colaborações anteriores e aprimoram suas decisões de delegação ao longo do tempo. + +## Próximos Passos + +- **Teste os exemplos**: Comece pelo exemplo básico de colaboração +- **Experimente diferentes papéis**: Teste combinações variadas de papéis de agentes +- **Monitore as interações**: Use `verbose=True` para ver a colaboração em ação +- **Otimize descrições de tarefas**: Tarefas claras geram melhor colaboração +- **Escale**: Experimente processos hierárquicos para projetos complexos + +A colaboração transforma agentes de IA individuais em equipes poderosas capazes de enfrentar desafios complexos e multifacetados juntos. \ No newline at end of file diff --git a/docs/pt-BR/concepts/crews.mdx b/docs/pt-BR/concepts/crews.mdx new file mode 100644 index 000000000..89a0641b7 --- /dev/null +++ b/docs/pt-BR/concepts/crews.mdx @@ -0,0 +1,366 @@ +--- +title: Crews +description: Compreendendo e utilizando crews no framework crewAI com atributos e funcionalidades abrangentes. +icon: people-group +--- + +## Visão Geral + +Uma crew no crewAI representa um grupo colaborativo de agentes trabalhando em conjunto para alcançar um conjunto de tarefas. Cada crew define a estratégia de execução de tarefas, colaboração entre agentes e o fluxo de trabalho geral. + +## Atributos de Crew + +| Atributo | Parâmetros | Descrição | +| :------------------------------------ | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Tasks** | `tasks` | Uma lista de tasks atribuídas à crew. | +| **Agents** | `agents` | Uma lista de agentes que fazem parte da crew. | +| **Process** _(opcional)_ | `process` | O fluxo de processo (por exemplo, sequencial, hierárquico) seguido pela crew. O padrão é `sequential`. | +| **Verbose** _(opcional)_ | `verbose` | O nível de verbosidade para logging durante a execução. O padrão é `False`. | +| **Manager LLM** _(opcional)_ | `manager_llm` | O modelo de linguagem utilizado pelo agente gerenciador em um processo hierárquico. **Obrigatório ao usar um processo hierárquico.** | +| **Function Calling LLM** _(opcional)_ | `function_calling_llm` | Se definido, a crew utilizará este LLM para invocar funções das ferramentas para todos os agentes da crew. Cada agente pode ter seu próprio LLM, que substitui o LLM da crew para chamadas de função. | +| **Config** _(opcional)_ | `config` | Configurações opcionais para a crew, no formato `Json` ou `Dict[str, Any]`. | +| **Max RPM** _(opcional)_ | `max_rpm` | Número máximo de requisições por minuto que a crew respeita durante a execução. O padrão é `None`. | +| **Memory** _(opcional)_ | `memory` | Utilizada para armazenar memórias de execução (curto prazo, longo prazo, memória de entidade). | +| **Memory Config** _(opcional)_ | `memory_config` | Configuração para o provedor de memória a ser utilizada pela crew. | +| **Cache** _(opcional)_ | `cache` | Especifica se deve usar cache para armazenar os resultados da execução de ferramentas. O padrão é `True`. | +| **Embedder** _(opcional)_ | `embedder` | Configuração do embedder a ser utilizado pela crew. Atualmente mais usado por memory. O padrão é `{"provider": "openai"}`. | +| **Step Callback** _(opcional)_ | `step_callback` | Uma função chamada após cada etapa de cada agente. Pode ser usada para registrar as ações do agente ou executar outras operações; não sobrescreve o `step_callback` específico do agente. | +| **Task Callback** _(opcional)_ | `task_callback` | Uma função chamada após a conclusão de cada tarefa. Útil para monitoramento ou para operações adicionais pós-execução da task. | +| **Share Crew** _(opcional)_ | `share_crew` | Se deseja compartilhar as informações completas da crew e execução com a equipe do crewAI para melhorar a biblioteca e nos permitir treinar modelos. | +| **Output Log File** _(opcional)_ | `output_log_file` | Defina como True para salvar logs como logs.txt no diretório atual ou forneça um caminho de arquivo. Os logs estarão em formato JSON se o nome terminar com .json, caso contrário .txt. O padrão é `None`. | +| **Manager Agent** _(opcional)_ | `manager_agent` | `manager` define um agente customizado que será utilizado como gerente. | +| **Prompt File** _(opcional)_ | `prompt_file` | Caminho para o arquivo JSON de prompt a ser utilizado pela crew. | +| **Planning** *(opcional)* | `planning` | Adiciona habilidade de planejamento à Crew. Quando ativado, antes de cada iteração, todos os dados da Crew são enviados a um AgentPlanner que planejará as tasks e este plano será adicionado à descrição de cada task. | +| **Planning LLM** *(opcional)* | `planning_llm` | O modelo de linguagem usado pelo AgentPlanner em um processo de planejamento. | + + +**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. + + +## Criando Crews + +Existem duas maneiras de criar crews no CrewAI: utilizando **configuração YAML (recomendado)** ou definindo diretamente **em código**. + +### Configuração YAML (Recomendado) + +O uso da configuração YAML proporciona uma forma mais limpa e fácil de manter para definir crews, sendo consistente com a definição de agentes e tasks em projetos CrewAI. + +Após criar seu projeto CrewAI conforme descrito na seção [Instalação](/pt-BR/installation), você pode definir sua crew em uma classe que herda de `CrewBase` e utiliza decorators para definir agentes, tarefas e a própria crew. + +#### Exemplo de Classe Crew com Decorators + +```python code +from crewai import Agent, Crew, Task, Process +from crewai.project import CrewBase, agent, task, crew, before_kickoff, after_kickoff +from crewai.agents.agent_builder.base_agent import BaseAgent +from typing import List + +@CrewBase +class YourCrewName: + """Descrição da sua crew""" + + agents: List[BaseAgent] + tasks: List[Task] + + # Caminhos para seus arquivos de configuração YAML + # Para um exemplo de agente e tarefa definidos em YAML, confira: + # - Task: https://docs.crewai.com/concepts/tasks#yaml-configuration-recommended + # - Agents: https://docs.crewai.com/concepts/agents#yaml-configuration-recommended + agents_config = 'config/agents.yaml' + tasks_config = 'config/tasks.yaml' + + @before_kickoff + def prepare_inputs(self, inputs): + # Modifique inputs antes da crew iniciar + inputs['additional_data'] = "Alguma informação extra" + return inputs + + @after_kickoff + def process_output(self, output): + # Modifique a saída após a crew finalizar + output.raw += "\nProcessado após kickoff." + return output + + @agent + def agent_one(self) -> Agent: + return Agent( + config=self.agents_config['agent_one'], # type: ignore[index] + verbose=True + ) + + @agent + def agent_two(self) -> Agent: + return Agent( + config=self.agents_config['agent_two'], # type: ignore[index] + verbose=True + ) + + @task + def task_one(self) -> Task: + return Task( + config=self.tasks_config['task_one'] # type: ignore[index] + ) + + @task + def task_two(self) -> Task: + return Task( + config=self.tasks_config['task_two'] # type: ignore[index] + ) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, # Coletado automaticamente pelo decorator @agent + tasks=self.tasks, # Coletado automaticamente pelo decorator @task + process=Process.sequential, + verbose=True, + ) +``` + +Como executar o código acima: + +```python code +YourCrewName().crew().kickoff(inputs={"any": "input here"}) +``` + + +As tarefas serão executadas na ordem em que forem definidas. + + +A classe `CrewBase`, junto com esses decorators, automatiza a coleta de agentes e tarefas, reduzindo a necessidade de gerenciamento manual. + +#### Visão geral dos Decorators de `annotations.py` + +O CrewAI fornece vários decorators no arquivo `annotations.py` que são usados para marcar métodos dentro de sua classe crew para tratamento especial: + +- `@CrewBase`: Marca a classe como classe base de crew. +- `@agent`: Denota um método que retorna um objeto `Agent`. +- `@task`: Denota um método que retorna um objeto `Task`. +- `@crew`: Denota o método que retorna o objeto `Crew`. +- `@before_kickoff`: (Opcional) Marca um método a ser executado antes da crew iniciar. +- `@after_kickoff`: (Opcional) Marca um método a ser executado após a crew finalizar. + +Esses decorators ajudam na organização da estrutura da sua crew e coletam automaticamente agentes e tasks sem precisar listá-los manualmente. + +### Definição Direta em Código (Alternativa) + +Como alternativa, você pode definir a crew diretamente em código sem utilizar arquivos de configuração YAML. + +```python code +from crewai import Agent, Crew, Task, Process +from crewai_tools import YourCustomTool + +class YourCrewName: + def agent_one(self) -> Agent: + return Agent( + role="Data Analyst", + goal="Analyze data trends in the market", + backstory="An experienced data analyst with a background in economics", + verbose=True, + tools=[YourCustomTool()] + ) + + def agent_two(self) -> Agent: + return Agent( + role="Market Researcher", + goal="Gather information on market dynamics", + backstory="A diligent researcher with a keen eye for detail", + verbose=True + ) + + def task_one(self) -> Task: + return Task( + description="Collect recent market data and identify trends.", + expected_output="A report summarizing key trends in the market.", + agent=self.agent_one() + ) + + def task_two(self) -> Task: + return Task( + description="Research factors affecting market dynamics.", + expected_output="An analysis of factors influencing the market.", + agent=self.agent_two() + ) + + def crew(self) -> Crew: + return Crew( + agents=[self.agent_one(), self.agent_two()], + tasks=[self.task_one(), self.task_two()], + process=Process.sequential, + verbose=True + ) +``` +Como executar o código acima: + +```python code +YourCrewName().crew().kickoff(inputs={}) +``` + +Neste exemplo: + +- Agentes e tarefas são definidos diretamente dentro da classe, sem decorators. +- Criamos e gerenciamos manualmente a lista de agentes e tasks. +- Essa abordagem fornece mais controle, mas pode ser menos sustentável para projetos maiores. + +## Saída da Crew + +A saída de uma crew no framework CrewAI é encapsulada na classe `CrewOutput`. +Essa classe fornece uma forma estruturada de acessar os resultados da execução da crew, incluindo vários formatos como string bruta, JSON e modelos Pydantic. +O `CrewOutput` inclui os resultados da tarefa final, uso de tokens e as saídas das tasks individuais. + +### Atributos do Crew Output + +| Atributo | Parâmetros | Tipo | Descrição | +| :--------------- | :------------- | :------------------------ | :------------------------------------------------------------------------------------------------ | +| **Raw** | `raw` | `str` | A saída bruta da crew. Este é o formato padrão da saída. | +| **Pydantic** | `pydantic` | `Optional[BaseModel]` | Um objeto modelo Pydantic representando a saída estruturada da crew. | +| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]`| Um dicionário representando a saída da crew em formato JSON. | +| **Tasks Output** | `tasks_output` | `List[TaskOutput]` | Uma lista de objetos `TaskOutput`, cada um representando a saída de uma task na crew. | +| **Token Usage** | `token_usage` | `Dict[str, Any]` | Um resumo do uso de tokens, oferecendo informações sobre a performance do modelo de linguagem. | + +### Métodos e Propriedades do Crew Output + +| Método/Propriedade | Descrição | +| :----------------- | :------------------------------------------------------------------------------------------------- | +| **json** | Retorna a representação em string JSON da saída da crew caso o formato seja JSON. | +| **to_dict** | Converte as saídas JSON e Pydantic em um dicionário. | +| **__str__** | Retorna a representação em string do resultado da crew, priorizando Pydantic, depois JSON, depois raw.| + +### Acessando a Saída da Crew + +Após executar uma crew, sua saída pode ser acessada pelo atributo `output` do objeto `Crew`. A classe `CrewOutput` oferece várias formas de interagir com esta saída. + +#### Exemplo + +```python Code +# Execução de exemplo da crew +crew = Crew( + agents=[research_agent, writer_agent], + tasks=[research_task, write_article_task], + verbose=True +) + +crew_output = crew.kickoff() + +# Acessando a saída da crew +print(f"Raw Output: {crew_output.raw}") +if crew_output.json_dict: + print(f"JSON Output: {json.dumps(crew_output.json_dict, indent=2)}") +if crew_output.pydantic: + print(f"Pydantic Output: {crew_output.pydantic}") +print(f"Tasks Output: {crew_output.tasks_output}") +print(f"Token Usage: {crew_output.token_usage}") +``` + +## Acessando Logs da Crew + +Você pode visualizar o log em tempo real da execução da crew, definindo `output_log_file` como `True(Boolean)` ou um `file_name(str)`. Suporta logging de eventos como tanto `file_name.txt` quanto `file_name.json`. +Se for `True(Boolean)`, salvará como `logs.txt`. + +Caso `output_log_file` seja `False(Boolean)` ou `None`, os logs não serão gerados. + +```python Code +# Salvar logs da crew +crew = Crew(output_log_file = True) # Logs serão salvos como logs.txt +crew = Crew(output_log_file = file_name) # Logs serão salvos como file_name.txt +crew = Crew(output_log_file = file_name.txt) # Logs serão salvos como file_name.txt +crew = Crew(output_log_file = file_name.json) # Logs serão salvos como file_name.json +``` + +## Utilização de Memória + +As crews podem utilizar memória (curto prazo, longo prazo e memória de entidade) para potencializar sua execução e aprendizado ao longo do tempo. Este recurso permite que as crews armazenem e recuperem memórias de execução, auxiliando na tomada de decisão e nas estratégias de execução de tasks. + +## Utilização de Cache + +Caches podem ser utilizados para armazenar resultados de execuções de ferramentas, tornando o processo mais eficiente ao evitar a reexecução de tasks idênticas. + +## Métricas de Uso da Crew + +Após a execução da crew, você pode acessar o atributo `usage_metrics` para visualizar as métricas de uso do modelo de linguagem (LLM) para todas as tasks executadas pela crew. Isso fornece insights sobre eficiência operacional e oportunidades de melhoria. + +```python Code +# Acessar as métricas de uso da crew +crew = Crew(agents=[agent1, agent2], tasks=[task1, task2]) +crew.kickoff() +print(crew.usage_metrics) +``` + +## Processo de Execução da Crew + +- **Sequential Process**: As tasks são executadas uma após a outra, permitindo um fluxo de trabalho linear. +- **Hierarchical Process**: Um agente gerente coordena a crew, delegando tarefas e validando resultados antes de prosseguir. **Nota**: Um `manager_llm` ou `manager_agent` é necessário para este processo e é essencial para validar o fluxo. + +### Iniciando uma Crew + +Uma vez que sua crew esteja montada, inicie o workflow com o método `kickoff()`. Isso inicia a execução conforme o fluxo de processo definido. + +```python Code +# Iniciar execução das tasks da crew +result = my_crew.kickoff() +print(result) +``` + +### Diferentes Formas de Iniciar uma Crew + +Assim que sua crew estiver definida, inicie o fluxo de trabalho com o método kickoff apropriado. O CrewAI oferece vários métodos para melhor controle do processo: `kickoff()`, `kickoff_for_each()`, `kickoff_async()` e `kickoff_for_each_async()`. + +- `kickoff()`: Inicia o processo de execução seguindo o fluxo definido. +- `kickoff_for_each()`: Executa tasks sequencialmente para cada evento de entrada ou item da coleção fornecida. +- `kickoff_async()`: Inicia o workflow de forma assíncrona. +- `kickoff_for_each_async()`: Executa as tasks concorrentemente para cada entrada, aproveitando o processamento assíncrono. + +```python Code +# Iniciar execução das tasks da crew +result = my_crew.kickoff() +print(result) + +# Exemplo com kickoff_for_each +inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}] +results = my_crew.kickoff_for_each(inputs=inputs_array) +for result in results: + print(result) + +# Exemplo com kickoff_async +inputs = {'topic': 'AI in healthcare'} +async_result = await my_crew.kickoff_async(inputs=inputs) +print(async_result) + +# Exemplo com kickoff_for_each_async +inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}] +async_results = await my_crew.kickoff_for_each_async(inputs=inputs_array) +for async_result in async_results: + print(async_result) +``` + +Esses métodos fornecem flexibilidade para gerenciar e executar tasks dentro de sua crew, permitindo fluxos de trabalho síncronos e assíncronos de acordo com sua necessidade. + +### Repetindo Execução a partir de uma Task Específica + +Agora é possível reiniciar a execução a partir de uma task específica usando o comando CLI `replay`. + +O recurso de replay no CrewAI permite reexecutar a partir de uma task específica através da interface de linha de comando (CLI). Rodando o comando `crewai replay -t `, 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 +``` + +Esses comandos permitem repetir tasks dos seus últimos kickoffs, mantendo o contexto das tasks já executadas anteriormente. diff --git a/docs/pt-BR/concepts/event-listener.mdx b/docs/pt-BR/concepts/event-listener.mdx new file mode 100644 index 000000000..cf24aa859 --- /dev/null +++ b/docs/pt-BR/concepts/event-listener.mdx @@ -0,0 +1,379 @@ +--- +title: 'Listeners de Evento' +description: 'Acesse eventos do CrewAI para criar integrações e monitoramento personalizados' +icon: spinner +--- + +## Visão Geral + +O CrewAI oferece um sistema de eventos poderoso que permite escutar e reagir a diversos eventos que ocorrem durante a execução do seu Crew. Esse recurso possibilita a criação de integrações personalizadas, soluções de monitoramento, sistemas de log ou qualquer outra funcionalidade que precise ser acionada com base nos eventos internos do CrewAI. + +## Como Funciona + +O CrewAI utiliza uma arquitetura de event bus para emitir eventos ao longo do ciclo de vida da execução. O sistema de eventos é construído a partir dos seguintes componentes: + +1. **CrewAIEventsBus**: Um event bus singleton que gerencia o registro e emissão de eventos +2. **BaseEvent**: Classe base para todos os eventos do sistema +3. **BaseEventListener**: Classe base abstrata para criar listeners de evento personalizados + +Quando ações específicas ocorrem no CrewAI (como a inicialização de um Crew, um Agent concluindo uma tarefa ou o uso de uma ferramenta), o sistema emite os eventos correspondentes. Você pode registrar handlers para esses eventos para executar código personalizado quando eles acontecerem. + + +O CrewAI Enterprise fornece o recurso Prompt Tracing, que aproveita o sistema de eventos para rastrear, armazenar e visualizar todos os prompts, respostas e metadados associados. Isso proporciona poderosas capacidades de depuração e transparência nas operações dos seus agentes. + +![Prompt Tracing Dashboard](/images/enterprise/traces-overview.png) + +Com o Prompt Tracing você pode: +- Visualizar o histórico completo de todos os prompts enviados ao seu LLM +- Monitorar o uso de tokens e custos +- Depurar falhas de raciocínio dos agentes +- Compartilhar sequências de prompts com sua equipe +- Comparar diferentes estratégias de prompts +- Exportar rastreamentos para compliance e auditoria + + +## Criando um Listener de Evento Personalizado + +Para criar um listener de evento personalizado, você precisa: + +1. Criar uma classe que herde de `BaseEventListener` +2. Implementar o método `setup_listeners` +3. Registrar handles para os eventos de seu interesse +4. Instanciar seu listener no arquivo apropriado + +Veja um exemplo simples de uma classe de listener de evento personalizado: + +```python +from crewai.utilities.events import ( + CrewKickoffStartedEvent, + CrewKickoffCompletedEvent, + AgentExecutionCompletedEvent, +) +from crewai.utilities.events.base_event_listener import BaseEventListener + +class MyCustomListener(BaseEventListener): + def __init__(self): + super().__init__() + + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(CrewKickoffStartedEvent) + def on_crew_started(source, event): + print(f"Crew '{event.crew_name}' has started execution!") + + @crewai_event_bus.on(CrewKickoffCompletedEvent) + def on_crew_completed(source, event): + print(f"Crew '{event.crew_name}' has completed execution!") + print(f"Output: {event.output}") + + @crewai_event_bus.on(AgentExecutionCompletedEvent) + def on_agent_execution_completed(source, event): + print(f"Agent '{event.agent.role}' completed task") + print(f"Output: {event.output}") +``` + +## Registrando Corretamente Seu Listener + +Apenas definir sua classe de listener não é suficiente. É necessário criar uma instância dela e garantir que ela seja importada na sua aplicação. Isso garante que: + +1. Os event handlers estejam registrados no event bus +2. A instância do listener permaneça em memória (não seja coletada pelo garbage collector) +3. O listener esteja ativo quando os eventos forem emitidos + +### Opção 1: Importar e Instanciar no Seu Crew ou Implementação de Flow + +O mais importante é criar uma instância do seu listener no arquivo onde seu Crew ou Flow está definido e executado: + +#### Para Aplicações Baseadas em Crew + +Crie e importe seu listener no início do arquivo de implementação do seu Crew: + +```python +# No seu arquivo crew.py +from crewai import Agent, Crew, Task +from my_listeners import MyCustomListener + +# Crie uma instância do seu listener +my_listener = MyCustomListener() + +class MyCustomCrew: + # Sua implementação do crew... + + def crew(self): + return Crew( + agents=[...], + tasks=[...], + # ... + ) +``` + +#### Para Aplicações Baseadas em Flow + +Crie e importe seu listener no início do arquivo de implementação do seu Flow: + +```python +# Em seu arquivo main.py ou flow.py +from crewai.flow import Flow, listen, start +from my_listeners import MyCustomListener + +# Crie uma instância do seu listener +my_listener = MyCustomListener() + +class MyCustomFlow(Flow): + # Sua implementação do flow... + + @start() + def first_step(self): + # ... +``` + +Isso assegura que seu listener será carregado e estará ativo quando seu Crew ou Flow for executado. + +### Opção 2: Criar um Pacote para Seus Listeners + +Para uma abordagem mais estruturada, especialmente se houver múltiplos listeners: + +1. Crie um pacote para seus listeners: + +``` +my_project/ + ├── listeners/ + │ ├── __init__.py + │ ├── my_custom_listener.py + │ └── another_listener.py +``` + +2. Em `my_custom_listener.py`, defina sua classe de listener e crie uma instância: + +```python +# my_custom_listener.py +from crewai.utilities.events.base_event_listener import BaseEventListener +# ... importe events ... + +class MyCustomListener(BaseEventListener): + # ... implementação ... + +# Crie uma instância do seu listener +my_custom_listener = MyCustomListener() +``` + +3. Em `__init__.py`, importe as instâncias dos listeners para garantir seu carregamento: + +```python +# __init__.py +from .my_custom_listener import my_custom_listener +from .another_listener import another_listener + +# Opcionalmente exporte-os se precisar acessá-los em outros lugares +__all__ = ['my_custom_listener', 'another_listener'] +``` + +4. Importe seu pacote de listeners no arquivo do seu Crew ou Flow: + +```python +# No seu arquivo crew.py ou flow.py +import my_project.listeners # Isso carrega todos os seus listeners + +class MyCustomCrew: + # Sua implementação do crew... +``` + +É exatamente assim que o `agentops_listener` integrado do CrewAI é registrado. No código-fonte do CrewAI, você encontrará: + +```python +# src/crewai/utilities/events/third_party/__init__.py +from .agentops_listener import agentops_listener +``` + +Isso garante que o `agentops_listener` seja carregado quando o pacote `crewai.utilities.events` for importado. + +## Tipos de Eventos Disponíveis + +O CrewAI fornece uma ampla variedade de eventos para escuta: + +### Eventos de Crew + +- **CrewKickoffStartedEvent**: Emitido quando um Crew inicia a execução +- **CrewKickoffCompletedEvent**: Emitido quando um Crew conclui a execução +- **CrewKickoffFailedEvent**: Emitido quando um Crew falha ao concluir a execução +- **CrewTestStartedEvent**: Emitido ao iniciar o teste de um Crew +- **CrewTestCompletedEvent**: Emitido ao concluir o teste de um Crew +- **CrewTestFailedEvent**: Emitido ao falhar no teste de um Crew +- **CrewTrainStartedEvent**: Emitido ao iniciar o treinamento de um Crew +- **CrewTrainCompletedEvent**: Emitido ao concluir o treinamento de um Crew +- **CrewTrainFailedEvent**: Emitido ao falhar no treinamento de um Crew + +### Eventos de Agent + +- **AgentExecutionStartedEvent**: Emitido quando um Agent inicia a execução de uma tarefa +- **AgentExecutionCompletedEvent**: Emitido quando um Agent conclui a execução de uma tarefa +- **AgentExecutionErrorEvent**: Emitido quando um Agent encontra um erro durante a execução + +### Eventos de Task + +- **TaskStartedEvent**: Emitido ao iniciar a execução de uma Task +- **TaskCompletedEvent**: Emitido ao concluir a execução de uma Task +- **TaskFailedEvent**: Emitido ao falhar na execução de uma Task +- **TaskEvaluationEvent**: Emitido quando uma Task é avaliada + +### Eventos de Uso de Ferramentas + +- **ToolUsageStartedEvent**: Emitido ao iniciar a execução de uma ferramenta +- **ToolUsageFinishedEvent**: Emitido ao concluir a execução de uma ferramenta +- **ToolUsageErrorEvent**: Emitido quando ocorre erro na execução de uma ferramenta +- **ToolValidateInputErrorEvent**: Emitido ao ocorrer erro de validação de entrada na ferramenta +- **ToolExecutionErrorEvent**: Emitido quando ocorre erro na execução de uma ferramenta +- **ToolSelectionErrorEvent**: Emitido ao ocorrer erro na seleção de uma ferramenta + +### Eventos de Knowledge + +- **KnowledgeRetrievalStartedEvent**: Emitido ao iniciar recuperação de conhecimento +- **KnowledgeRetrievalCompletedEvent**: Emitido ao concluir recuperação de conhecimento +- **KnowledgeQueryStartedEvent**: Emitido ao iniciar consulta de conhecimento +- **KnowledgeQueryCompletedEvent**: Emitido ao concluir consulta de conhecimento +- **KnowledgeQueryFailedEvent**: Emitido ao falhar consulta de conhecimento +- **KnowledgeSearchQueryFailedEvent**: Emitido ao falhar consulta de busca de conhecimento + +### Eventos de Guardrail do LLM + +- **LLMGuardrailStartedEvent**: Emitido ao iniciar validação dos guardrails. Contém detalhes do guardrail aplicado e tentativas. +- **LLMGuardrailCompletedEvent**: Emitido ao concluir validação dos guardrails. Contém detalhes sobre sucesso/falha na validação, resultados e mensagens de erro, se houver. + +### Eventos de Flow + +- **FlowCreatedEvent**: Emitido ao criar um Flow +- **FlowStartedEvent**: Emitido ao iniciar a execução de um Flow +- **FlowFinishedEvent**: Emitido ao concluir a execução de um Flow +- **FlowPlotEvent**: Emitido ao plotar um Flow +- **MethodExecutionStartedEvent**: Emitido ao iniciar a execução de um método do Flow +- **MethodExecutionFinishedEvent**: Emitido ao concluir a execução de um método do Flow +- **MethodExecutionFailedEvent**: Emitido ao falhar na execução de um método do Flow + +### Eventos de LLM + +- **LLMCallStartedEvent**: Emitido ao iniciar uma chamada LLM +- **LLMCallCompletedEvent**: Emitido ao concluir uma chamada LLM +- **LLMCallFailedEvent**: Emitido ao falhar uma chamada LLM +- **LLMStreamChunkEvent**: Emitido para cada chunk recebido durante respostas em streaming do LLM + +## Estrutura dos Handlers de Evento + +Cada handler de evento recebe dois parâmetros: + +1. **source**: O objeto que emitiu o evento +2. **event**: A instância do evento, contendo dados específicos do evento + +A estrutura do objeto de evento depende do tipo do evento, mas todos herdam de `BaseEvent` e incluem: + +- **timestamp**: O horário em que o evento foi emitido +- **type**: Identificador do tipo do evento + +Campos adicionais variam pelo tipo de evento. Por exemplo, `CrewKickoffCompletedEvent` inclui os campos `crew_name` e `output`. + +## Exemplo Real: Integração com AgentOps + +O CrewAI inclui um exemplo de integração com [AgentOps](https://github.com/AgentOps-AI/agentops), uma plataforma de monitoramento e observabilidade para agentes de IA. Veja como é implementado: + +```python +from typing import Optional + +from crewai.utilities.events import ( + CrewKickoffCompletedEvent, + ToolUsageErrorEvent, + ToolUsageStartedEvent, +) +from crewai.utilities.events.base_event_listener import BaseEventListener +from crewai.utilities.events.crew_events import CrewKickoffStartedEvent +from crewai.utilities.events.task_events import TaskEvaluationEvent + +try: + import agentops + AGENTOPS_INSTALLED = True +except ImportError: + AGENTOPS_INSTALLED = False + +class AgentOpsListener(BaseEventListener): + tool_event: Optional["agentops.ToolEvent"] = None + session: Optional["agentops.Session"] = None + + def __init__(self): + super().__init__() + + def setup_listeners(self, crewai_event_bus): + if not AGENTOPS_INSTALLED: + return + + @crewai_event_bus.on(CrewKickoffStartedEvent) + def on_crew_kickoff_started(source, event: CrewKickoffStartedEvent): + self.session = agentops.init() + for agent in source.agents: + if self.session: + self.session.create_agent( + name=agent.role, + agent_id=str(agent.id), + ) + + @crewai_event_bus.on(CrewKickoffCompletedEvent) + def on_crew_kickoff_completed(source, event: CrewKickoffCompletedEvent): + if self.session: + self.session.end_session( + end_state="Success", + end_state_reason="Finished Execution", + ) + + @crewai_event_bus.on(ToolUsageStartedEvent) + def on_tool_usage_started(source, event: ToolUsageStartedEvent): + self.tool_event = agentops.ToolEvent(name=event.tool_name) + if self.session: + self.session.record(self.tool_event) + + @crewai_event_bus.on(ToolUsageErrorEvent) + def on_tool_usage_error(source, event: ToolUsageErrorEvent): + agentops.ErrorEvent(exception=event.error, trigger_event=self.tool_event) +``` + +Esse listener inicializa uma sessão do AgentOps quando um Crew inicia, cadastra agentes no AgentOps, rastreia o uso de ferramentas e finaliza a sessão quando o Crew é concluído. + +O listener AgentOps é registrado no sistema de eventos do CrewAI via importação em `src/crewai/utilities/events/third_party/__init__.py`: + +```python +from .agentops_listener import agentops_listener +``` + +Isso garante que o `agentops_listener` seja carregado quando o pacote `crewai.utilities.events` for importado. + +## Uso Avançado: Handlers Escopados + +Para lidar temporariamente com eventos (útil para testes ou operações específicas), você pode usar o context manager `scoped_handlers`: + +```python +from crewai.utilities.events import crewai_event_bus, CrewKickoffStartedEvent + +with crewai_event_bus.scoped_handlers(): + @crewai_event_bus.on(CrewKickoffStartedEvent) + def temp_handler(source, event): + print("Este handler só existe neste contexto") + + # Faça algo que emita eventos + +# Fora do contexto, o handler temporário é removido +``` + +## Casos de Uso + +Listeners de evento podem ser usados para várias finalidades: + +1. **Log e Monitoramento**: Monitore a execução do seu Crew e registre eventos importantes +2. **Analytics**: Colete dados sobre o desempenho e comportamento do seu Crew +3. **Depuração**: Configure listeners temporários para debugar problemas específicos +4. **Integração**: Conecte o CrewAI a sistemas externos como plataformas de monitoramento, bancos de dados ou serviços de notificação +5. **Comportamento Personalizado**: Dispare ações personalizadas com base em eventos específicos + +## Boas Práticas + +1. **Mantenha Handlers Leves**: Handlers de eventos devem ser leves e evitar operações bloqueantes +2. **Tratamento de Erros**: Implemente tratamento de erros adequado nos event handlers para evitar que exceções afetem a execução principal +3. **Limpeza**: Se seu listener alocar recursos, garanta o devido fechamento/liberação +4. **Escuta Seletiva**: Escute apenas eventos que realmente precisa tratar +5. **Testes**: Teste seus listeners de evento isoladamente para garantir que se comportam conforme esperado + +Aproveitando o sistema de eventos do CrewAI, é possível estender a funcionalidade e integrá-lo facilmente à sua infraestrutura existente. \ No newline at end of file diff --git a/docs/pt-BR/concepts/flows.mdx b/docs/pt-BR/concepts/flows.mdx new file mode 100644 index 000000000..433a53d1e --- /dev/null +++ b/docs/pt-BR/concepts/flows.mdx @@ -0,0 +1,509 @@ +--- +title: Flows +description: Saiba como criar e gerenciar fluxos de trabalho de IA usando CrewAI Flows. +icon: arrow-progress +--- + +## Visão Geral + +O CrewAI Flows é um recurso poderoso projetado para simplificar a criação e o gerenciamento de fluxos de trabalho de IA. Os flows permitem que desenvolvedores combinem e coordenem tarefas de codificação e crews de forma eficiente, proporcionando uma estrutura robusta para a construção de automações de IA sofisticadas. + +Os flows permitem que você crie fluxos de trabalho estruturados e orientados por eventos. Eles oferecem uma forma integrada de conectar múltiplas tarefas, gerenciar estado e controlar o fluxo de execução nas suas aplicações de IA. Com flows, você pode facilmente projetar e implementar processos de múltiplas etapas que exploram todo o potencial das capacidades do CrewAI. + +1. **Criação Simplificada de Fluxos de Trabalho**: Conecte facilmente múltiplas crews e tarefas para criar workflows de IA complexos. + +2. **Gerenciamento de Estado**: Flows facilitam muito o gerenciamento e o compartilhamento de estados entre diferentes tarefas do seu fluxo de trabalho. + +3. **Arquitetura Orientada a Eventos**: Construído sobre um modelo orientado a eventos, permitindo fluxos dinâmicos e responsivos. + +4. **Controle de Fluxo Flexível**: Implemente lógica condicional, loops e ramificações dentro dos seus fluxos. + +## Primeiros Passos + +Vamos criar um Flow simples no qual você usará a OpenAI para gerar uma cidade aleatória em uma tarefa e, em seguida, usará essa cidade para gerar uma curiosidade em outra tarefa. + +```python Code +# (O código não é traduzido) +``` + +Na ilustração acima, criamos um Flow simples que gera uma cidade aleatória usando a OpenAI e depois cria uma curiosidade sobre essa cidade. O Flow consiste em duas tarefas: `generate_city` e `generate_fun_fact`. A tarefa `generate_city` é o ponto de início do Flow, enquanto a tarefa `generate_fun_fact` fica escutando o resultado da tarefa `generate_city`. + +Cada instância de Flow recebe automaticamente um identificador único (UUID) em seu estado, que auxilia no rastreamento e gerenciamento das execuções. O estado também pode armazenar dados adicionais (como a cidade gerada e a curiosidade) que permanecem durante toda a execução do flow. + +Ao executar o Flow, ele irá: +1. Gerar um ID único para o estado do flow +2. Gerar uma cidade aleatória e armazená-la no estado +3. Gerar uma curiosidade sobre essa cidade e armazená-la no estado +4. Imprimir os resultados no console + +O ID único do estado e os dados armazenados podem ser úteis para rastrear execuções do flow e manter contexto entre as tarefas. + +**Nota:** Certifique-se de configurar seu arquivo `.env` para armazenar sua `OPENAI_API_KEY`. Essa chave é necessária para autenticar as requisições à API da OpenAI. + +### @start() + +O decorador `@start()` é utilizado para marcar um método como ponto inicial de um Flow. Quando um Flow é iniciado, todos os métodos decorados com `@start()` são executados em paralelo. É possível ter múltiplos métodos start em um Flow, e todos eles serão executados quando o Flow iniciar. + +### @listen() + +O decorador `@listen()` é utilizado para marcar um método como ouvinte da saída de outra tarefa do Flow. O método decorado com `@listen()` será executado quando a tarefa especificada emitir uma saída. O método pode acessar a saída da tarefa à qual está escutando como argumento. + +#### Utilização + +O decorador `@listen()` pode ser usado de várias formas: + +1. **Escutando um Método pelo Nome**: Você pode passar o nome do método ao qual deseja escutar como string. Quando esse método concluir, o método ouvinte será chamado. + + ```python Code + # (O código não é traduzido) + ``` + +2. **Escutando um Método Diretamente**: Você pode passar o próprio método. Quando esse método concluir, o método ouvinte será chamado. + ```python Code + # (O código não é traduzido) + ``` + +### Saída de um Flow + +Acessar e manipular a saída de um Flow é essencial para integrar seus workflows de IA a aplicações ou sistemas maiores. O CrewAI Flows fornece mecanismos fáceis para recuperar a saída final, acessar resultados intermediários e gerenciar o estado geral do seu Flow. + +#### Recuperando a Saída Final + +Ao executar um Flow, a saída final é determinada pelo último método concluído. O método `kickoff()` retorna a saída desse método final. + +Veja como acessar a saída final: + + +```python Code +# (O código não é traduzido) +``` + +```text Output +---- Final Output ---- +Second method received: Output from first_method +``` + + +![Flow Visual image](/images/crewai-flow-2.png) + +Neste exemplo, o `second_method` é o último método a ser concluído, logo sua saída será a saída final do Flow. +O método `kickoff()` retorna essa saída, que é impressa no console. O método `plot()` irá gerar o arquivo HTML para visualizar o fluxo. + +#### Acessando e Atualizando o Estado + +Além de recuperar a saída final, você pode acessar e atualizar o estado dentro do seu Flow. O estado pode ser usado para armazenar e compartilhar dados entre diferentes métodos do Flow. Após a execução do Flow, você pode acessar o estado para recuperar informações adicionadas ou alteradas durante o processo. + +Veja um exemplo de como atualizar e acessar o estado: + + +```python Code +# (O código não é traduzido) +``` + +```text Output +Final Output: Hello from first_method - updated by second_method +Final State: +counter=2 message='Hello from first_method - updated by second_method' +``` + + +![Flow Visual image](/images/crewai-flow-2.png) + +Neste exemplo, o estado é atualizado tanto por `first_method` quanto por `second_method`. +Após o término da execução, é possível acessar o estado final e observar as atualizações realizadas por esses métodos. + +Ao garantir que a saída do método final seja retornada e oferecer acesso ao estado, o CrewAI Flows facilita a integração dos resultados dos seus workflows de IA em aplicações maiores, +além de permitir o gerenciamento e o acesso ao estado durante toda a execução do Flow. + +## Gerenciamento de Estado em Flows + +Gerenciar o estado de forma eficaz é fundamental para construir fluxos de trabalho de IA confiáveis e de fácil manutenção. O CrewAI Flows oferece mecanismos robustos para o gerenciamento de estado tanto não estruturado quanto estruturado, +permitindo que o desenvolvedor escolha a abordagem que melhor se adapta à sua aplicação. + +### Gerenciamento de Estado Não Estruturado + +No gerenciamento de estado não estruturado, todo o estado é armazenado no atributo `state` da classe `Flow`. +Essa abordagem oferece flexibilidade, permitindo que o desenvolvedor adicione ou modifique atributos do estado conforme necessário sem precisar definir um esquema rígido. +Mesmo com estados não estruturados, os flows do CrewAI geram e mantêm automaticamente um identificador único (UUID) para cada instância de estado. + +```python Code +# (O código não é traduzido) +``` + +![Flow Visual image](/images/crewai-flow-3.png) + +**Nota:** O campo `id` é gerado e preservado automaticamente durante toda a execução do flow. Não é necessário gerenciá-lo ou defini-lo manualmente, e ele permanecerá mesmo ao atualizar o estado com novos dados. + +**Pontos-Chave:** + +- **Flexibilidade:** É possível adicionar atributos dinamicamente ao `self.state` sem restrições pré-definidas. +- **Simplicidade:** Ideal para fluxos de trabalho diretos em que a estrutura do estado é mínima ou varia bastante. + +### Gerenciamento de Estado Estruturado + +No gerenciamento de estado estruturado, utilizam-se esquemas pré-definidos para garantir consistência e segurança de tipos em todo o workflow. +Ao usar modelos como o `BaseModel` da Pydantic, os desenvolvedores podem definir a forma exata do estado, melhorando a validação e fornecendo auto-complete nos ambientes de desenvolvimento. + +Cada estado nos flows do CrewAI recebe automaticamente um identificador único (UUID) para ajudar no rastreamento e gerenciamento. Esse ID é gerado e mantido automaticamente pelo sistema de flows. + +```python Code +# (O código não é traduzido) +``` + +![Flow Visual image](/images/crewai-flow-3.png) + +**Pontos-Chave:** + +- **Esquema Definido:** `ExampleState` deixa claro a estrutura do estado, aumentando a legibilidade e a manutenção do código. +- **Segurança de Tipos:** O uso da Pydantic garante que os atributos do estado tenham os tipos certos, reduzindo os erros em tempo de execução. +- **Auto-Completar:** IDEs conseguem oferecer auto-completar e checagem de erros, graças ao modelo definido do estado. + +### Escolhendo entre Estado Não Estruturado e Estruturado + +- **Use Estado Não Estruturado quando:** + - O estado do fluxo é simples ou altamente dinâmico. + - Flexibilidade é mais importante do que uma definição rígida do estado. + - Prototipagem rápida é necessária sem a sobrecarga de definição de esquemas. + +- **Use Estado Estruturado quando:** + - O flow exige uma estrutura de estado bem definida e consistente. + - Segurança de tipos e validação são importantes para a confiabilidade da aplicação. + - É desejado usar recursos da IDE como auto-completar e checagem de tipos para uma melhor experiência de desenvolvimento. + +Ao oferecer as duas opções de gerenciamento de estado, o CrewAI Flows permite que desenvolvedores criem fluxos de IA que sejam ao mesmo tempo flexíveis e robustos, atendendo a uma ampla variedade de requisitos de aplicação. + +## Persistência de Flow + +O decorador @persist permite a persistência automática do estado nos flows do CrewAI, garantindo que você mantenha o estado do flow entre reinicializações ou execuções diferentes do workflow. Esse decorador pode ser aplicado tanto ao nível de classe, quanto ao nível de método, oferecendo flexibilidade sobre como gerenciar a persistência do estado. + +### Persistência no Nível de Classe + +Quando aplicado no nível da classe, o decorador @persist garante a persistência automática de todos os estados dos métodos do flow: + +```python +# (O código não é traduzido) +``` + +### Persistência no Nível de Método + +Para um controle mais granular, você pode aplicar @persist em métodos específicos: + +```python +# (O código não é traduzido) +``` + +### Como Funciona + +1. **Identificação Única do Estado** + - Cada estado do flow recebe automaticamente um UUID único + - O ID é preservado entre atualizações do estado e chamadas de métodos + - Suporta tanto estados estruturados (Pydantic BaseModel) quanto não estruturados (dicionário) + +2. **Backend SQLite Padrão** + - O SQLiteFlowPersistence é o backend de armazenamento padrão + - Os estados são salvos automaticamente em um banco de dados SQLite local + - O tratamento de erros é robusto, oferecendo mensagens claras caso ocorram falhas nas operações de banco de dados + +3. **Tratamento de Erros** + - Mensagens de erro abrangentes para operações de banco de dados + - Validação automática do estado ao salvar e carregar + - Feedback claro quando houver problemas de persistência + +### Considerações Importantes + +- **Tipos de Estado**: São suportados tanto estados estruturados (Pydantic BaseModel) quanto não estruturados (dicionário) +- **ID Automático**: O campo `id` é adicionado automaticamente se não estiver presente +- **Recuperação de Estado**: Flows que falharem ou forem reiniciados podem recarregar automaticamente seu estado anterior +- **Implementação Personalizada**: Você pode fornecer sua própria implementação de FlowPersistence para necessidades de armazenamento especializadas + +### Vantagens Técnicas + +1. **Controle Preciso Através de Acesso de Baixo Nível** + - Acesso direto às operações de persistência para casos avançados + - Controle detalhado via decoradores de persistência no nível do método + - Inspeção de estado e recursos de depuração embutidos + - Visibilidade total das mudanças e operações de persistência do estado + +2. **Maior Confiabilidade** + - Recuperação automática do estado após falhas no sistema ou reinicializações + - Atualizações de estado baseadas em transações para garantir integridade dos dados + - Mensagens de erro abrangentes e claras + - Validação robusta durante operações de salvar e carregar estado + +3. **Arquitetura Extensível** + - Backend de persistência personalizável através da interface FlowPersistence + - Suporte para soluções de armazenamento especializadas além do SQLite + - Compatibilidade tanto com estados estruturados (Pydantic) quanto não estruturados (dict) + - Integração perfeita com os padrões de flow existentes no CrewAI + +A arquitetura de persistência enfatiza precisão técnica e opções de personalização, permitindo que desenvolvedores mantenham controle total sobre o gerenciamento de estado enquanto se beneficiam dos recursos de confiabilidade integrados. + +## Controle de Flow + +### Lógica Condicional: `or` + +A função `or_` nos flows permite escutar múltiplos métodos e acionar o método ouvinte quando qualquer um dos métodos especificados gerar uma saída. + + +```python Code +# (O código não é traduzido) +``` + +```text Output +Logger: Hello from the start method +Logger: Hello from the second method +``` + + +![Flow Visual image](/images/crewai-flow-4.png) + +Ao executar esse Flow, o método `logger` será acionado pela saída tanto do `start_method` quanto do `second_method`. +A função `or_` serve para escutar vários métodos e disparar o método ouvinte quando qualquer um emitir um resultado. + +### Lógica Condicional: `and` + +A função `and_` nos flows permite escutar múltiplos métodos e acionar o método ouvinte apenas quando todos os métodos especificados emitirem uma saída. + + +```python Code +# (O código não é traduzido) +``` + +```text Output +---- Logger ---- +{'greeting': 'Hello from the start method', 'joke': 'What do computers eat? Microchips.'} +``` + + +![Flow Visual image](/images/crewai-flow-5.png) + +Ao executar esse Flow, o método `logger` só será disparado quando ambos `start_method` e `second_method` emitirem uma saída. +A função `and_` é usada para escutar vários métodos e acionar o método ouvinte apenas quando todas as condições forem atendidas. + +### Router + +O decorador `@router()` nos flows permite definir lógica de roteamento condicional baseada na saída de um método. +Você pode especificar diferentes rotas conforme a saída do método, permitindo controlar o fluxo de execução de forma dinâmica. + + +```python Code +# (O código não é traduzido) +``` + +```text Output +Starting the structured flow +Third method running +Fourth method running +``` + + +![Flow Visual image](/images/crewai-flow-6.png) + +No exemplo, o `start_method` gera um valor booleano aleatório e armazena no estado. +O `second_method` usa o decorador `@router()` para decidir o roteamento conforme o valor booleano. +Se o valor for `True`, retorna `"success"`, senão retorna `"failed"`. +Os métodos `third_method` e `fourth_method` escutam a saída do `second_method` e executam com base no valor retornado. + +Ao executar esse Flow, a saída será diferente dependendo do valor booleano aleatório gerado pelo `start_method`. + +## Adicionando Agentes aos Flows + +Os agentes podem ser integrados facilmente aos seus flows, oferecendo uma alternativa leve às crews completas quando você precisar executar tarefas simples e focadas. Veja um exemplo de como utilizar um agente em um flow para realizar uma pesquisa de mercado: + +```python +# (O código não é traduzido) +``` + +![Flow Visual image](/images/crewai-flow-7.png) + +Esse exemplo demonstra diversos recursos fundamentais do uso de agentes em flows: + +1. **Saída Estruturada**: O uso de modelos Pydantic para definir o formato esperado da saída (`MarketAnalysis`) garante segurança de tipos e dados estruturados em todo o flow. + +2. **Gerenciamento de Estado**: O estado do flow (`MarketResearchState`) mantém o contexto entre as etapas e armazena entradas e saídas. + +3. **Integração de Ferramentas**: Os agentes podem usar ferramentas (como `WebsiteSearchTool`) para potencializar suas habilidades. + +## Adicionando Crews aos Flows + +Criar um flow com múltiplas crews no CrewAI é simples. + +Você pode gerar um novo projeto CrewAI que já inclui toda a estrutura para criar um flow com várias crews executando o seguinte comando: + +```bash +crewai create flow name_of_flow +``` + +Esse comando irá gerar um novo projeto CrewAI com a estrutura de pastas necessária. O projeto gerado inclui uma crew pré-criada chamada `poem_crew`, já funcional. Você pode usar essa crew como modelo, copiando, colando e editando para criar outras crews. + +### Estrutura de Pastas + +Após rodar o comando `crewai create flow name_of_flow`, você verá uma estrutura parecida com: + +| Diretório/Arquivo | Descrição | +| :------------------------ | :------------------------------------------------------------------- | +| `name_of_flow/` | Diretório raiz do flow. | +| ├── `crews/` | Contém diretórios para crews específicas. | +| │ └── `poem_crew/` | Diretório da "poem_crew" com configurações e scripts. | +| │ ├── `config/` | Arquivos de configuração da "poem_crew". | +| │ │ ├── `agents.yaml` | YAML que define os agentes da "poem_crew". | +| │ │ └── `tasks.yaml` | YAML que define as tarefas da "poem_crew". | +| │ ├── `poem_crew.py` | Script da funcionalidade da "poem_crew". | +| ├── `tools/` | Ferramentas adicionais usadas no flow. | +| │ └── `custom_tool.py` | Implementação de ferramenta customizada. | +| ├── `main.py` | Script principal do flow. | +| ├── `README.md` | Descrição do projeto e instruções. | +| ├── `pyproject.toml` | Arquivo de configurações e dependências do projeto. | +| └── `.gitignore` | Arquivos e pastas a serem ignorados no controle de versão. | + +### Construindo suas Crews + +Na pasta `crews`, você pode definir múltiplas crews. Cada crew tem sua própria pasta, com arquivos de configuração e o arquivo de definição da crew. Por exemplo, a pasta `poem_crew` contém: + +- `config/agents.yaml`: Define os agentes da crew. +- `config/tasks.yaml`: Define as tarefas da crew. +- `poem_crew.py`: Contém a definição da crew, incluindo agentes, tarefas, etc. + +Você pode copiar, colar e editar a `poem_crew` para criar outras crews. + +### Conectando Crews no `main.py` + +No arquivo `main.py`, você cria seu flow e conecta as crews. É possível definir o fluxo usando a classe `Flow` e os decoradores `@start` e `@listen` para definir a ordem de execução. + +Veja um exemplo de como conectar a `poem_crew` no arquivo `main.py`: + +```python Code +# (O código não é traduzido) +``` + +Neste exemplo, a classe `PoemFlow` define um fluxo que gera a quantidade de frases, usa a `PoemCrew` para gerar um poema e, depois, salva o poema em um arquivo. O flow inicia com o método `kickoff()`, e o gráfico é gerado pelo método `plot()`. + +![Flow Visual image](/images/crewai-flow-8.png) + +### Executando o Flow + +(Opcional) Antes de rodar o flow, instale as dependências executando: + +```bash +crewai install +``` + +Após instalar as dependências, ative o ambiente virtual com: + +```bash +source .venv/bin/activate +``` + +Com o ambiente ativado, execute o flow usando um dos comandos: + +```bash +crewai flow kickoff +``` + +ou + +```bash +uv run kickoff +``` + +O flow será executado, e você verá a saída no console. + +## Plotando Flows + +Visualizar seus fluxos de trabalho de IA proporciona insights valiosos sobre a estrutura e os caminhos de execução dos flows. O CrewAI oferece uma ferramenta de visualização poderosa que permite gerar plots interativos dos flows, facilitando o entendimento e a otimização dos workflows de IA. + +### O que são Plots? + +No CrewAI, plots são representações gráficas dos fluxos de trabalho de IA. Eles mostram as tarefas, suas conexões e o fluxo de dados entre elas. Essa visualização ajuda a compreender a sequência de operações, identificar gargalos e garantir que a lógica do workflow está alinhada com o esperado. + +### Como Gerar um Plot + +O CrewAI oferece duas formas práticas de gerar plots dos seus flows: + +#### Opção 1: Usando o método `plot()` + +Se estiver trabalhando diretamente com uma instância do flow, basta chamar o método `plot()` do objeto. Isso criará um arquivo HTML com o plot interativo do seu flow. + +```python Code +# (O código não é traduzido) +``` + +Esse comando gera um arquivo chamado `my_flow_plot.html` no diretório atual. Abra esse arquivo em um navegador para visualizar o plot interativo. + +#### Opção 2: Usando a Linha de Comando + +Em projetos CrewAI estruturados, é possível gerar um plot pela linha de comando. Isso é útil para projetos maiores, onde você deseja visualizar toda a configuração do flow. + +```bash +crewai flow plot +``` + +O comando gera um arquivo HTML com o plot do flow, semelhante ao método `plot()`. Basta abrir o arquivo no navegador para explorar o workflow. + +### Entendendo o Plot + +O plot gerado mostra nós representando as tarefas do seu flow, com setas indicando o fluxo de execução. A visualização é interativa, permitindo zoom, navegação e detalhes ao passar o mouse nos nós. + +Ao visualizar seus flows, você tem clareza do formato do workflow, facilitando debug, otimização e comunicação dos seus processos de IA para outras pessoas. + +### Conclusão + +A plotagem dos flows é um recurso poderoso do CrewAI para aprimorar o design e o gerenciamento de fluxos de IA complexos. Usando o método `plot()` ou a linha de comando, você obtém uma visão visual dos workflows, benefício tanto para desenvolvimento quanto para apresentação. + +## Próximos Passos + +Se você deseja explorar exemplos adicionais de flows, acompanhe alguns exemplos em nosso repositório de exemplos. Aqui estão quatro sugestões específicas de flows, cada uma demonstrando casos de uso distintos para você escolher conforme seu problema: + +1. **Email Auto Responder Flow**: Este exemplo demonstra um loop infinito, onde um job de background roda continuamente automatizando respostas de email. É ideal para tarefas rotineiras sem intervenção manual. [Ver Exemplo](https://github.com/crewAIInc/crewAI-examples/tree/main/email_auto_responder_flow) + +2. **Lead Score Flow**: Destaca como adicionar feedback humano e manipular diferentes ramos condicionais usando router. Um ótimo aprendizado para workflows com decisão dinâmica e supervisão humana. [Ver Exemplo](https://github.com/crewAIInc/crewAI-examples/tree/main/lead-score-flow) + +3. **Write a Book Flow**: Exemplo ideal para encadear múltiplas crews, onde a saída de uma é usada por outra. Uma crew faz um sumário do livro inteiro, outra gera capítulos... Tudo conectado para entregar um livro completo. Perfeito para processos longos e coordenados. [Ver Exemplo](https://github.com/crewAIInc/crewAI-examples/tree/main/write_a_book_with_flows) + +4. **Meeting Assistant Flow**: Demonstra como transmitir um evento para desencadear múltiplas ações posteriores. Exemplo: ao finalizar uma reunião, atualizar um Trello, enviar mensagem no Slack e salvar resultados ao mesmo tempo. Indicado para gerenciamento completo de tarefas e notificações. [Ver Exemplo](https://github.com/crewAIInc/crewAI-examples/tree/main/meeting_assistant_flow) + +Explore esses exemplos para descobrir como aproveitar CrewAI Flows em diferentes contextos – desde automação de tarefas repetitivas até o gerenciamento de processos dinâmicos com decisões e feedback humano. + +Além disso, confira nosso vídeo no YouTube sobre como utilizar flows no CrewAI abaixo! + + + +## Executando Flows + +Existem duas formas de executar um flow: + +### Usando a API do Flow + +Você pode executar um flow programaticamente criando uma instância da sua classe de flow e chamando o método `kickoff()`: + +```python +flow = ExampleFlow() +result = flow.kickoff() +``` + +### Usando a CLI + +A partir da versão 0.103.0, é possível executar flows usando o comando `crewai run`: + +```shell +crewai run +``` + +O comando detecta automaticamente se seu projeto é um flow (com base na configuração `type = "flow"` no pyproject.toml) e executa conforme o esperado. Esse é o método recomendado para executar flows pelo terminal. + +Por compatibilidade retroativa, também é possível usar: + +```shell +crewai flow kickoff +``` + +No entanto, o comando `crewai run` é agora o preferido, pois funciona tanto para crews quanto para flows. \ No newline at end of file diff --git a/docs/pt-BR/concepts/knowledge.mdx b/docs/pt-BR/concepts/knowledge.mdx new file mode 100644 index 000000000..faac60437 --- /dev/null +++ b/docs/pt-BR/concepts/knowledge.mdx @@ -0,0 +1,1059 @@ +--- +title: Knowledge +description: O que é knowledge em CrewAI e como usá-lo. +icon: book +--- + +## Visão Geral + +Knowledge no CrewAI é um sistema poderoso que permite que agentes de IA acessem e utilizem fontes de informação externas durante suas tarefas. +Pense nisso como dar aos seus agentes uma biblioteca de referência que eles podem consultar enquanto trabalham. + + + Principais benefícios de usar Knowledge: + - Aprimorar agentes com informações específicas do domínio + - Apoiar decisões com dados do mundo real + - Manter contexto entre conversas + - Fundamentar respostas em informações factuais + + +## Exemplos de Início Rápido + + +Para Fontes de Knowledge baseadas em arquivos, certifique-se de colocar seus arquivos em um diretório `knowledge` na raiz do seu projeto. +Além disso, use caminhos relativos do diretório `knowledge` ao criar a fonte. + + +### Exemplo Básico de Knowledge com String + +```python Code +from crewai import Agent, Task, Crew, Process, LLM +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +# Create a knowledge source +content = "Users name is John. He is 30 years old and lives in San Francisco." +string_source = StringKnowledgeSource(content=content) + +# Create an LLM with a temperature of 0 to ensure deterministic outputs +llm = LLM(model="gpt-4o-mini", temperature=0) + +# Create an agent with the knowledge store +agent = Agent( + role="About User", + goal="You know everything about the user.", + backstory="You are a master at understanding people and their preferences.", + verbose=True, + allow_delegation=False, + llm=llm, +) + +task = Task( + description="Answer the following questions about the user: {question}", + expected_output="An answer to the question.", + agent=agent, +) + +crew = Crew( + agents=[agent], + tasks=[task], + verbose=True, + process=Process.sequential, + knowledge_sources=[string_source], # Enable knowledge by adding the sources here +) + +result = crew.kickoff(inputs={"question": "What city does John live in and how old is he?"}) +``` + +### Exemplo de Knowledge com Conteúdo Web + + + Você precisa instalar `docling` para o seguinte exemplo funcionar: `uv add docling` + + +```python Code +from crewai import LLM, Agent, Crew, Process, Task +from crewai.knowledge.source.crew_docling_source import CrewDoclingSource + +# Create a knowledge source from web content +content_source = CrewDoclingSource( + file_paths=[ + "https://lilianweng.github.io/posts/2024-11-28-reward-hacking", + "https://lilianweng.github.io/posts/2024-07-07-hallucination", + ], +) + +# Create an LLM with a temperature of 0 to ensure deterministic outputs +llm = LLM(model="gpt-4o-mini", temperature=0) + +# Create an agent with the knowledge store +agent = Agent( + role="About papers", + goal="You know everything about the papers.", + backstory="You are a master at understanding papers and their content.", + verbose=True, + allow_delegation=False, + llm=llm, +) + +task = Task( + description="Answer the following questions about the papers: {question}", + expected_output="An answer to the question.", + agent=agent, +) + +crew = Crew( + agents=[agent], + tasks=[task], + verbose=True, + process=Process.sequential, + knowledge_sources=[content_source], +) + +result = crew.kickoff( + inputs={"question": "What is the reward hacking paper about? Be sure to provide sources."} +) +``` + +## Fontes de Knowledge Suportadas + +O CrewAI suporta vários tipos de fontes de knowledge prontas para uso: + + + + - Strings brutas + - Arquivos de texto (.txt) + - Documentos PDF + + + - Arquivos CSV + - Planilhas Excel + - Documentos JSON + + + +### Fonte de Knowledge de Arquivo de Texto +```python +from crewai.knowledge.source.text_file_knowledge_source import TextFileKnowledgeSource + +text_source = TextFileKnowledgeSource( + file_paths=["document.txt", "another.txt"] +) +``` + +### Fonte de Knowledge PDF +```python +from crewai.knowledge.source.pdf_knowledge_source import PDFKnowledgeSource + +pdf_source = PDFKnowledgeSource( + file_paths=["document.pdf", "another.pdf"] +) +``` + +### Fonte de Knowledge CSV +```python +from crewai.knowledge.source.csv_knowledge_source import CSVKnowledgeSource + +csv_source = CSVKnowledgeSource( + file_paths=["data.csv"] +) +``` + +### Fonte de Knowledge Excel +```python +from crewai.knowledge.source.excel_knowledge_source import ExcelKnowledgeSource + +excel_source = ExcelKnowledgeSource( + file_paths=["spreadsheet.xlsx"] +) +``` + +### Fonte de Knowledge JSON +```python +from crewai.knowledge.source.json_knowledge_source import JSONKnowledgeSource + +json_source = JSONKnowledgeSource( + file_paths=["data.json"] +) +``` + + + Certifique-se de criar a pasta ./knowledge. Todos os arquivos de origem (ex: .txt, .pdf, .xlsx, .json) devem ser colocados nesta pasta para gerenciamento centralizado. + + +## Knowledge de Agente vs Crew: Guia Completo + + +**Entendendo os Níveis de Knowledge**: O CrewAI suporta knowledge tanto no nível de agente quanto de crew. Esta seção esclarece exatamente como cada um funciona, quando são inicializados, e aborda equívocos comuns sobre dependências. + + +### Como a Inicialização de Knowledge Realmente Funciona + +Aqui está exatamente o que acontece quando você usa knowledge: + +#### Knowledge no Nível do Agente (Independente) +```python +from crewai import Agent, Task, Crew +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +# Agent with its own knowledge - NO crew knowledge needed +specialist_knowledge = StringKnowledgeSource( + content="Specialized technical information for this agent only" +) + +specialist_agent = Agent( + role="Technical Specialist", + goal="Provide technical expertise", + backstory="Expert in specialized technical domains", + knowledge_sources=[specialist_knowledge] # Agent-specific knowledge +) + +task = Task( + description="Answer technical questions", + agent=specialist_agent, + expected_output="Technical answer" +) + +# No crew-level knowledge required +crew = Crew( + agents=[specialist_agent], + tasks=[task] +) + +result = crew.kickoff() # Agent knowledge works independently +``` + +#### O Que Acontece Durante `crew.kickoff()` + +Quando você chama `crew.kickoff()`, aqui está a sequência exata: + +```python +# During kickoff +for agent in self.agents: + agent.crew = self # Agent gets reference to crew + agent.set_knowledge(crew_embedder=self.embedder) # Agent knowledge initialized + agent.create_agent_executor() +``` + +#### Independência de Armazenamento + +Cada nível de knowledge usa coleções de armazenamento independentes: + +```python +# Agent knowledge storage +agent_collection_name = agent.role # e.g., "Technical Specialist" + +# Crew knowledge storage +crew_collection_name = "crew" + +# Both stored in same ChromaDB instance but different collections +# Path: ~/.local/share/CrewAI/{project}/knowledge/ +# ├── crew/ # Crew knowledge collection +# ├── Technical Specialist/ # Agent knowledge collection +# └── Another Agent Role/ # Another agent's collection +``` + +### Exemplos Completos Funcionais + +#### Exemplo 1: Knowledge Apenas do Agente +```python +from crewai import Agent, Task, Crew +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +# Agent-specific knowledge +agent_knowledge = StringKnowledgeSource( + content="Agent-specific information that only this agent needs" +) + +agent = Agent( + role="Specialist", + goal="Use specialized knowledge", + backstory="Expert with specific knowledge", + knowledge_sources=[agent_knowledge], + embedder={ # Agent can have its own embedder + "provider": "openai", + "config": {"model": "text-embedding-3-small"} + } +) + +task = Task( + description="Answer using your specialized knowledge", + agent=agent, + expected_output="Answer based on agent knowledge" +) + +# No crew knowledge needed +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() # Works perfectly +``` + +#### Exemplo 2: Knowledge Tanto do Agente Quanto da Crew +```python +# Crew-wide knowledge (shared by all agents) +crew_knowledge = StringKnowledgeSource( + content="Company policies and general information for all agents" +) + +# Agent-specific knowledge +specialist_knowledge = StringKnowledgeSource( + content="Technical specifications only the specialist needs" +) + +specialist = Agent( + role="Technical Specialist", + goal="Provide technical expertise", + backstory="Technical expert", + knowledge_sources=[specialist_knowledge] # Agent-specific +) + +generalist = Agent( + role="General Assistant", + goal="Provide general assistance", + backstory="General helper" + # No agent-specific knowledge +) + +crew = Crew( + agents=[specialist, generalist], + tasks=[...], + knowledge_sources=[crew_knowledge] # Crew-wide knowledge +) + +# Result: +# - specialist gets: crew_knowledge + specialist_knowledge +# - generalist gets: crew_knowledge only +``` + +#### Exemplo 3: Múltiplos Agentes com Knowledge Diferente +```python +# Different knowledge for different agents +sales_knowledge = StringKnowledgeSource(content="Sales procedures and pricing") +tech_knowledge = StringKnowledgeSource(content="Technical documentation") +support_knowledge = StringKnowledgeSource(content="Support procedures") + +sales_agent = Agent( + role="Sales Representative", + knowledge_sources=[sales_knowledge], + embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}} +) + +tech_agent = Agent( + role="Technical Expert", + knowledge_sources=[tech_knowledge], + embedder={"provider": "ollama", "config": {"model": "mxbai-embed-large"}} +) + +support_agent = Agent( + role="Support Specialist", + knowledge_sources=[support_knowledge] + # Will use crew embedder as fallback +) + +crew = Crew( + agents=[sales_agent, tech_agent, support_agent], + tasks=[...], + embedder={ # Fallback embedder for agents without their own + "provider": "google", + "config": {"model": "text-embedding-004"} + } +) + +# Each agent gets only their specific knowledge +# Each can use different embedding providers +``` + + +Diferente da recuperação de um banco de dados vetorial usando uma ferramenta, agentes pré-carregados com knowledge não precisarão de uma persona de recuperação ou tarefa. +Simplesmente adicione as fontes de knowledge relevantes que seu agente ou crew precisa para funcionar. + +As fontes de knowledge podem ser adicionadas no nível do agente ou da crew. +As fontes de knowledge no nível da crew serão usadas por **todos os agentes** na crew. +As fontes de knowledge no nível do agente serão usadas pelo **agente específico** que é pré-carregado com o knowledge. + + +## Configuração de Knowledge + +Você pode configurar a configuração de knowledge para a crew ou agente. + +```python Code +from crewai.knowledge.knowledge_config import KnowledgeConfig + +knowledge_config = KnowledgeConfig(results_limit=10, score_threshold=0.5) + +agent = Agent( + ... + knowledge_config=knowledge_config +) +``` + + + `results_limit`: é o número de documentos relevantes a retornar. Padrão é 3. + `score_threshold`: é a pontuação mínima para um documento ser considerado relevante. Padrão é 0.35. + + +## Parâmetros de Knowledge Suportados + + + Lista de fontes de knowledge que fornecem conteúdo para ser armazenado e consultado. Pode incluir PDF, CSV, Excel, JSON, arquivos de texto ou conteúdo de string. + + + Nome da coleção onde o knowledge será armazenado. Usado para identificar diferentes conjuntos de knowledge. Padrão é "knowledge" se não fornecido. + + +Configuração de armazenamento personalizada para gerenciar como o knowledge é armazenado e recuperado. Se não fornecido, um armazenamento padrão será criado. + + +## Transparência do Armazenamento de Knowledge + + +**Entendendo o Armazenamento de Knowledge**: O CrewAI armazena automaticamente as fontes de knowledge em diretórios específicos da plataforma usando ChromaDB para armazenamento vetorial. Entender essas localizações e padrões ajuda com implantações de produção, depuração e gerenciamento de armazenamento. + + +### Onde o CrewAI Armazena Arquivos de Knowledge + +Por padrão, o CrewAI usa o mesmo sistema de armazenamento que a memória, armazenando knowledge em diretórios específicos da plataforma: + +#### Localizações de Armazenamento Padrão por Plataforma + +**macOS:** +``` +~/Library/Application Support/CrewAI/{project_name}/ +└── knowledge/ # Knowledge ChromaDB files + ├── chroma.sqlite3 # ChromaDB metadata + ├── {collection_id}/ # Vector embeddings + └── knowledge_{collection}/ # Named collections +``` + +**Linux:** +``` +~/.local/share/CrewAI/{project_name}/ +└── knowledge/ + ├── chroma.sqlite3 + ├── {collection_id}/ + └── knowledge_{collection}/ +``` + +**Windows:** +``` +C:\Users\{username}\AppData\Local\CrewAI\{project_name}\ +└── knowledge\ + ├── chroma.sqlite3 + ├── {collection_id}\ + └── knowledge_{collection}\ +``` + +### Encontrando Sua Localização de Armazenamento de Knowledge + +Para ver exatamente onde o CrewAI está armazenando seus arquivos de knowledge: + +```python +from crewai.utilities.paths import db_storage_path +import os + +# Get the knowledge storage path +knowledge_path = os.path.join(db_storage_path(), "knowledge") +print(f"Knowledge storage location: {knowledge_path}") + +# List knowledge collections and files +if os.path.exists(knowledge_path): + print("\nKnowledge storage contents:") + for item in os.listdir(knowledge_path): + item_path = os.path.join(knowledge_path, item) + if os.path.isdir(item_path): + print(f"📁 Collection: {item}/") + # Show collection contents + try: + for subitem in os.listdir(item_path): + print(f" └── {subitem}") + except PermissionError: + print(f" └── (permission denied)") + else: + print(f"📄 {item}") +else: + print("No knowledge storage found yet.") +``` + +### Controlando Localizações de Armazenamento de Knowledge + +#### Opção 1: Variável de Ambiente (Recomendado) +```python +import os +from crewai import Crew + +# Set custom storage location for all CrewAI data +os.environ["CREWAI_STORAGE_DIR"] = "./my_project_storage" + +# All knowledge will now be stored in ./my_project_storage/knowledge/ +crew = Crew( + agents=[...], + tasks=[...], + knowledge_sources=[...] +) +``` + +#### Opção 2: Armazenamento de Knowledge Personalizado +```python +from crewai.knowledge.storage.knowledge_storage import KnowledgeStorage +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +# Create custom storage with specific embedder +custom_storage = KnowledgeStorage( + embedder={ + "provider": "ollama", + "config": {"model": "mxbai-embed-large"} + }, + collection_name="my_custom_knowledge" +) + +# Use with knowledge sources +knowledge_source = StringKnowledgeSource( + content="Your knowledge content here" +) +knowledge_source.storage = custom_storage +``` + +#### Opção 3: Armazenamento de Knowledge Específico do Projeto +```python +import os +from pathlib import Path + +# Store knowledge in project directory +project_root = Path(__file__).parent +knowledge_dir = project_root / "knowledge_storage" + +os.environ["CREWAI_STORAGE_DIR"] = str(knowledge_dir) + +# Now all knowledge will be stored in your project directory +``` + +### Comportamento Padrão do Provedor de Embedding + + +**Provedor de Embedding Padrão**: O CrewAI usa por padrão embeddings da OpenAI (`text-embedding-3-small`) para armazenamento de knowledge, mesmo quando usa diferentes provedores de LLM. Você pode facilmente personalizar isso para corresponder à sua configuração. + + +#### Entendendo o Comportamento Padrão +```python +from crewai import Agent, Crew, LLM +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +# When using Claude as your LLM... +agent = Agent( + role="Researcher", + goal="Research topics", + backstory="Expert researcher", + llm=LLM(provider="anthropic", model="claude-3-sonnet") # Using Claude +) + +# CrewAI will still use OpenAI embeddings by default for knowledge +# This ensures consistency but may not match your LLM provider preference +knowledge_source = StringKnowledgeSource(content="Research data...") + +crew = Crew( + agents=[agent], + tasks=[...], + knowledge_sources=[knowledge_source] + # Default: Uses OpenAI embeddings even with Claude LLM +) +``` + +#### Personalizando Provedores de Embedding de Knowledge +```python +# Option 1: Use Voyage AI (recommended by Anthropic for Claude users) +crew = Crew( + agents=[agent], + tasks=[...], + knowledge_sources=[knowledge_source], + embedder={ + "provider": "voyageai", # Recommended for Claude users + "config": { + "api_key": "your-voyage-api-key", + "model": "voyage-3" # or "voyage-3-large" for best quality + } + } +) + +# Option 2: Use local embeddings (no external API calls) +crew = Crew( + agents=[agent], + tasks=[...], + knowledge_sources=[knowledge_source], + embedder={ + "provider": "ollama", + "config": { + "model": "mxbai-embed-large", + "url": "http://localhost:11434/api/embeddings" + } + } +) + +# Option 3: Agent-level embedding customization +agent = Agent( + role="Researcher", + goal="Research topics", + backstory="Expert researcher", + knowledge_sources=[knowledge_source], + embedder={ + "provider": "google", + "config": { + "model": "models/text-embedding-004", + "api_key": "your-google-key" + } + } +) +``` + +#### Configurando Embeddings do Azure OpenAI + +Ao usar embeddings do Azure OpenAI: +1. Certifique-se de implantar o modelo de embedding na plataforma Azure primeiro +2. Então você precisa usar a seguinte configuração: + +```python +agent = Agent( + role="Researcher", + goal="Research topics", + backstory="Expert researcher", + knowledge_sources=[knowledge_source], + embedder={ + "provider": "azure", + "config": { + "api_key": "your-azure-api-key", + "model": "text-embedding-ada-002", # change to the model you are using and is deployed in Azure + "api_base": "https://your-azure-endpoint.openai.azure.com/", + "api_version": "2024-02-01" + } + } +) +``` + +## Recursos Avançados + +### Reescrita de Consulta + +O CrewAI implementa um mecanismo inteligente de reescrita de consulta para otimizar a recuperação de knowledge. Quando um agente precisa pesquisar nas fontes de knowledge, o prompt da tarefa bruto é automaticamente transformado em uma consulta de pesquisa mais eficaz. + +#### Como a Reescrita de Consulta Funciona + +1. Quando um agente executa uma tarefa com fontes de knowledge disponíveis, o método `_get_knowledge_search_query` é acionado +2. O LLM do agente é usado para transformar o prompt original da tarefa em uma consulta de pesquisa otimizada +3. Esta consulta otimizada é então usada para recuperar informações relevantes das fontes de knowledge + +#### Benefícios da Reescrita de Consulta + + + + Ao focar em conceitos-chave e remover conteúdo irrelevante, a reescrita de consulta ajuda a recuperar informações mais relevantes. + + + As consultas reescritas são projetadas para ser mais específicas e conscientes do contexto para recuperação de banco de dados vetorial. + + + +#### Exemplo + +```python +# Original task prompt +task_prompt = "Answer the following questions about the user's favorite movies: What movie did John watch last week? Format your answer in JSON." + +# Behind the scenes, this might be rewritten as: +rewritten_query = "What movies did John watch last week?" +``` + +A consulta reescrita é mais focada na necessidade de informação principal e remove instruções irrelevantes sobre formatação de saída. + + + Este mecanismo é totalmente automático e não requer configuração dos usuários. O LLM do agente é usado para realizar a reescrita da consulta, então usar um LLM mais capaz pode melhorar a qualidade das consultas reescritas. + + +### Eventos de Knowledge + +O CrewAI emite eventos durante o processo de recuperação de knowledge que você pode escutar usando o sistema de eventos. Esses eventos permitem que você monitore, depure e analise como o knowledge está sendo recuperado e usado pelos seus agentes. + +#### Eventos de Knowledge Disponíveis + +- **KnowledgeRetrievalStartedEvent**: Emitido quando um agente começa a recuperar knowledge das fontes +- **KnowledgeRetrievalCompletedEvent**: Emitido quando a recuperação de knowledge é concluída, incluindo a consulta usada e o conteúdo recuperado +- **KnowledgeQueryStartedEvent**: Emitido quando uma consulta às fontes de knowledge começa +- **KnowledgeQueryCompletedEvent**: Emitido quando uma consulta é concluída com sucesso +- **KnowledgeQueryFailedEvent**: Emitido quando uma consulta às fontes de knowledge falha +- **KnowledgeSearchQueryFailedEvent**: Emitido quando uma consulta de pesquisa falha + +#### Exemplo: Monitorando Recuperação de Knowledge + +```python +from crewai.utilities.events import ( + KnowledgeRetrievalStartedEvent, + KnowledgeRetrievalCompletedEvent, +) +from crewai.utilities.events.base_event_listener import BaseEventListener + +class KnowledgeMonitorListener(BaseEventListener): + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(KnowledgeRetrievalStartedEvent) + def on_knowledge_retrieval_started(source, event): + print(f"Agent '{event.agent.role}' started retrieving knowledge") + + @crewai_event_bus.on(KnowledgeRetrievalCompletedEvent) + def on_knowledge_retrieval_completed(source, event): + print(f"Agent '{event.agent.role}' completed knowledge retrieval") + print(f"Query: {event.query}") + print(f"Retrieved {len(event.retrieved_knowledge)} knowledge chunks") + +# Create an instance of your listener +knowledge_monitor = KnowledgeMonitorListener() +``` + +Para mais informações sobre como usar eventos, consulte a documentação [Event Listeners](https://docs.crewai.com/concepts/event-listener). + +### Fontes de Knowledge Personalizadas + +O CrewAI permite que você crie fontes de knowledge personalizadas para qualquer tipo de dados estendendo a classe `BaseKnowledgeSource`. Vamos criar um exemplo prático que busca e processa artigos de notícias espaciais. + +#### Exemplo de Fonte de Knowledge de Notícias Espaciais + + + +```python Code +from crewai import Agent, Task, Crew, Process, LLM +from crewai.knowledge.source.base_knowledge_source import BaseKnowledgeSource +import requests +from datetime import datetime +from typing import Dict, Any +from pydantic import BaseModel, Field + +class SpaceNewsKnowledgeSource(BaseKnowledgeSource): + """Knowledge source that fetches data from Space News API.""" + + api_endpoint: str = Field(description="API endpoint URL") + limit: int = Field(default=10, description="Number of articles to fetch") + + def load_content(self) -> Dict[Any, str]: + """Fetch and format space news articles.""" + try: + response = requests.get( + f"{self.api_endpoint}?limit={self.limit}" + ) + response.raise_for_status() + + data = response.json() + articles = data.get('results', []) + + formatted_data = self.validate_content(articles) + return {self.api_endpoint: formatted_data} + except Exception as e: + raise ValueError(f"Failed to fetch space news: {str(e)}") + + def validate_content(self, articles: list) -> str: + """Format articles into readable text.""" + formatted = "Space News Articles:\n\n" + for article in articles: + formatted += f""" + Title: {article['title']} + Published: {article['published_at']} + Summary: {article['summary']} + News Site: {article['news_site']} + URL: {article['url']} + -------------------""" + return formatted + + def add(self) -> None: + """Process and store the articles.""" + content = self.load_content() + for _, text in content.items(): + chunks = self._chunk_text(text) + self.chunks.extend(chunks) + + self._save_documents() + +# Create knowledge source +recent_news = SpaceNewsKnowledgeSource( + api_endpoint="https://api.spaceflightnewsapi.net/v4/articles", + limit=10, +) + +# Create specialized agent +space_analyst = Agent( + role="Space News Analyst", + goal="Answer questions about space news accurately and comprehensively", + backstory="""You are a space industry analyst with expertise in space exploration, + satellite technology, and space industry trends. You excel at answering questions + about space news and providing detailed, accurate information.""", + knowledge_sources=[recent_news], + llm=LLM(model="gpt-4", temperature=0.0) +) + +# Create task that handles user questions +analysis_task = Task( + description="Answer this question about space news: {user_question}", + expected_output="A detailed answer based on the recent space news articles", + agent=space_analyst +) + +# Create and run the crew +crew = Crew( + agents=[space_analyst], + tasks=[analysis_task], + verbose=True, + process=Process.sequential +) + +# Example usage +result = crew.kickoff( + inputs={"user_question": "What are the latest developments in space exploration?"} +) +``` + +```output Output +# Agent: Space News Analyst +## Task: Answer this question about space news: What are the latest developments in space exploration? + + +# Agent: Space News Analyst +## Final Answer: +The latest developments in space exploration, based on recent space news articles, include the following: + +1. SpaceX has received the final regulatory approvals to proceed with the second integrated Starship/Super Heavy launch, scheduled for as soon as the morning of Nov. 17, 2023. This is a significant step in SpaceX's ambitious plans for space exploration and colonization. [Source: SpaceNews](https://spacenews.com/starship-cleared-for-nov-17-launch/) + +2. SpaceX has also informed the US Federal Communications Commission (FCC) that it plans to begin launching its first next-generation Starlink Gen2 satellites. This represents a major upgrade to the Starlink satellite internet service, which aims to provide high-speed internet access worldwide. [Source: Teslarati](https://www.teslarati.com/spacex-first-starlink-gen2-satellite-launch-2022/) + +3. AI startup Synthetaic has raised $15 million in Series B funding. The company uses artificial intelligence to analyze data from space and air sensors, which could have significant applications in space exploration and satellite technology. [Source: SpaceNews](https://spacenews.com/ai-startup-synthetaic-raises-15-million-in-series-b-funding/) + +4. The Space Force has formally established a unit within the U.S. Indo-Pacific Command, marking a permanent presence in the Indo-Pacific region. This could have significant implications for space security and geopolitics. [Source: SpaceNews](https://spacenews.com/space-force-establishes-permanent-presence-in-indo-pacific-region/) + +5. Slingshot Aerospace, a space tracking and data analytics company, is expanding its network of ground-based optical telescopes to increase coverage of low Earth orbit. This could improve our ability to track and analyze objects in low Earth orbit, including satellites and space debris. [Source: SpaceNews](https://spacenews.com/slingshots-space-tracking-network-to-extend-coverage-of-low-earth-orbit/) + +6. The National Natural Science Foundation of China has outlined a five-year project for researchers to study the assembly of ultra-large spacecraft. This could lead to significant advancements in spacecraft technology and space exploration capabilities. [Source: SpaceNews](https://spacenews.com/china-researching-challenges-of-kilometer-scale-ultra-large-spacecraft/) + +7. The Center for AEroSpace Autonomy Research (CAESAR) at Stanford University is focusing on spacecraft autonomy. The center held a kickoff event on May 22, 2024, to highlight the industry, academia, and government collaboration it seeks to foster. This could lead to significant advancements in autonomous spacecraft technology. [Source: SpaceNews](https://spacenews.com/stanford-center-focuses-on-spacecraft-autonomy/) +``` + + + +## Depuração e Solução de Problemas + +### Depurando Problemas de Knowledge + +#### Verificar Inicialização de Knowledge do Agente +```python +from crewai import Agent, Crew, Task +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +knowledge_source = StringKnowledgeSource(content="Test knowledge") + +agent = Agent( + role="Test Agent", + goal="Test knowledge", + backstory="Testing", + knowledge_sources=[knowledge_source] +) + +crew = Crew(agents=[agent], tasks=[Task(...)]) + +# Before kickoff - knowledge not initialized +print(f"Before kickoff - Agent knowledge: {getattr(agent, 'knowledge', None)}") + +crew.kickoff() + +# After kickoff - knowledge initialized +print(f"After kickoff - Agent knowledge: {agent.knowledge}") +print(f"Agent knowledge collection: {agent.knowledge.storage.collection_name}") +print(f"Number of sources: {len(agent.knowledge.sources)}") +``` + +#### Verificar Localizações de Armazenamento de Knowledge +```python +import os +from crewai.utilities.paths import db_storage_path + +# Check storage structure +storage_path = db_storage_path() +knowledge_path = os.path.join(storage_path, "knowledge") + +if os.path.exists(knowledge_path): + print("Knowledge collections found:") + for collection in os.listdir(knowledge_path): + collection_path = os.path.join(knowledge_path, collection) + if os.path.isdir(collection_path): + print(f" - {collection}/") + # Show collection contents + for item in os.listdir(collection_path): + print(f" └── {item}") +``` + +#### Testar Recuperação de Knowledge +```python +# Test agent knowledge retrieval +if hasattr(agent, 'knowledge') and agent.knowledge: + test_query = ["test query"] + results = agent.knowledge.query(test_query) + print(f"Agent knowledge results: {len(results)} documents found") + + # Test crew knowledge retrieval (if exists) + if hasattr(crew, 'knowledge') and crew.knowledge: + crew_results = crew.query_knowledge(test_query) + print(f"Crew knowledge results: {len(crew_results)} documents found") +``` + +#### Inspecionar Coleções de Knowledge +```python +import chromadb +from crewai.utilities.paths import db_storage_path +import os + +# Connect to CrewAI's knowledge ChromaDB +knowledge_path = os.path.join(db_storage_path(), "knowledge") + +if os.path.exists(knowledge_path): + client = chromadb.PersistentClient(path=knowledge_path) + collections = client.list_collections() + + print("Knowledge Collections:") + for collection in collections: + print(f" - {collection.name}: {collection.count()} documents") + + # Sample a few documents to verify content + if collection.count() > 0: + sample = collection.peek(limit=2) + print(f" Sample content: {sample['documents'][0][:100]}...") +else: + print("No knowledge storage found") +``` + +#### Verificar Processamento de Knowledge +```python +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +# Create a test knowledge source +test_source = StringKnowledgeSource( + content="Test knowledge content for debugging", + chunk_size=100, # Small chunks for testing + chunk_overlap=20 +) + +# Check chunking behavior +print(f"Original content length: {len(test_source.content)}") +print(f"Chunk size: {test_source.chunk_size}") +print(f"Chunk overlap: {test_source.chunk_overlap}") + +# Process and inspect chunks +test_source.add() +print(f"Number of chunks created: {len(test_source.chunks)}") +for i, chunk in enumerate(test_source.chunks[:3]): # Show first 3 chunks + print(f"Chunk {i+1}: {chunk[:50]}...") +``` + +### Problemas Comuns de Armazenamento de Knowledge + +**Erros "Arquivo não encontrado":** +```python +# Ensure files are in the correct location +from crewai.utilities.constants import KNOWLEDGE_DIRECTORY +import os + +knowledge_dir = KNOWLEDGE_DIRECTORY # Usually "knowledge" +file_path = os.path.join(knowledge_dir, "your_file.pdf") + +if not os.path.exists(file_path): + print(f"File not found: {file_path}") + print(f"Current working directory: {os.getcwd()}") + print(f"Expected knowledge directory: {os.path.abspath(knowledge_dir)}") +``` + +**Erros "Incompatibilidade de dimensão de embedding":** +```python +# This happens when switching embedding providers +# Reset knowledge storage to clear old embeddings +crew.reset_memories(command_type='knowledge') + +# Or use consistent embedding providers +crew = Crew( + agents=[...], + tasks=[...], + knowledge_sources=[...], + embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}} +) +``` + +**Erros "ChromaDB permissão negada":** +```bash +# Fix storage permissions +chmod -R 755 ~/.local/share/CrewAI/ +``` + +**Knowledge não persistindo entre execuções:** +```python +# Verify storage location consistency +import os +from crewai.utilities.paths import db_storage_path + +print("CREWAI_STORAGE_DIR:", os.getenv("CREWAI_STORAGE_DIR")) +print("Computed storage path:", db_storage_path()) +print("Knowledge path:", os.path.join(db_storage_path(), "knowledge")) +``` + +### Comandos de Reset de Knowledge + +```python +# Reset only agent-specific knowledge +crew.reset_memories(command_type='agent_knowledge') + +# Reset both crew and agent knowledge +crew.reset_memories(command_type='knowledge') + +# CLI commands +# crewai reset-memories --agent-knowledge # Agent knowledge only +# crewai reset-memories --knowledge # All knowledge +``` + +### Limpando Knowledge + +Se você precisar limpar o knowledge armazenado no CrewAI, você pode usar o comando `crewai reset-memories` com a opção `--knowledge`. + +```bash Command +crewai reset-memories --knowledge +``` + +Isso é útil quando você atualizou suas fontes de knowledge e quer garantir que os agentes estejam usando as informações mais recentes. + +## Melhores Práticas + + + + - Mantenha tamanhos de chunk apropriados para seu tipo de conteúdo + - Considere sobreposição de conteúdo para preservação de contexto + - Organize informações relacionadas em fontes de knowledge separadas + + + + - Ajuste tamanhos de chunk baseado na complexidade do conteúdo + - Configure modelos de embedding apropriados + - Considere usar provedores de embedding locais para processamento mais rápido + + + + - Com a estrutura de arquivo típica fornecida pelo CrewAI, as fontes de knowledge são incorporadas toda vez que o kickoff é acionado. + - Se as fontes de knowledge são grandes, isso leva à ineficiência e latência aumentada, pois os mesmos dados são incorporados cada vez. + - Para resolver isso, inicialize diretamente o parâmetro knowledge em vez do parâmetro knowledge_sources. + - Link para a issue para ter a ideia completa [Github Issue](https://github.com/crewAIInc/crewAI/issues/2755) + + + + - Use knowledge no nível do agente para informações específicas do papel + - Use knowledge no nível da crew para informações compartilhadas que todos os agentes precisam + - Configure embedders no nível do agente se você precisar de estratégias de embedding diferentes + - Use nomenclatura consistente de coleção mantendo papéis de agente descritivos + - Teste a inicialização de knowledge verificando agent.knowledge após o kickoff + - Monitore localizações de armazenamento para entender onde o knowledge está armazenado + - Reset knowledge apropriadamente usando os tipos de comando corretos + + + + - Configure `CREWAI_STORAGE_DIR` para uma localização conhecida em produção + - Escolha provedores de embedding explícitos para corresponder à sua configuração de LLM e evitar conflitos de chave de API + - Monitore o tamanho do armazenamento de knowledge conforme ele cresce com adições de documentos + - Organize fontes de knowledge por domínio ou propósito usando nomes de coleção + - Inclua diretórios de knowledge em suas estratégias de backup e implantação + - Configure permissões de arquivo apropriadas para arquivos de knowledge e diretórios de armazenamento + - Use variáveis de ambiente para chaves de API e configuração sensível + + diff --git a/docs/pt-BR/concepts/llms.mdx b/docs/pt-BR/concepts/llms.mdx new file mode 100644 index 000000000..e608b915d --- /dev/null +++ b/docs/pt-BR/concepts/llms.mdx @@ -0,0 +1,884 @@ +--- +title: 'LLMs' +description: 'Um guia abrangente para configurar e usar Modelos de Linguagem de Grande Escala (LLMs) em seus projetos CrewAI' +icon: 'microchip-ai' +--- + +## Visão Geral + +O CrewAI integra-se com múltiplos provedores de LLM através do LiteLLM, oferecendo flexibilidade para você escolher o modelo certo para o seu caso de uso específico. Este guia irá ajudá-lo a entender como configurar e usar diferentes provedores de LLM em seus projetos CrewAI. + +## O que são LLMs? + +Modelos de Linguagem de Grande Escala (LLMs) são a inteligência central por trás dos agentes CrewAI. Eles permitem que os agentes compreendam o contexto, tomem decisões e gerem respostas semelhantes às humanas. Veja o que você precisa saber: + + + + Modelos de Linguagem de Grande Escala são sistemas de IA treinados em grandes volumes de dados textuais. Eles potencializam a inteligência dos agentes CrewAI, permitindo compreender e gerar textos de voz humana. + + + A janela de contexto determina quanto texto um LLM pode processar de uma só vez. Janelas maiores (por exemplo, 128K tokens) permitem mais contexto, porém podem ser mais caras e lentas. + + + A temperatura (0.0 a 1.0) controla a aleatoriedade das respostas. Valores mais baixos (ex.: 0.2) produzem respostas mais focadas e determinísticas, enquanto valores mais altos (ex.: 0.8) aumentam criatividade e variabilidade. + + + Cada provedor de LLM (ex.: OpenAI, Anthropic, Google) oferece modelos diferentes, com capacidades, preços e recursos variados. Escolha conforme suas necessidades de precisão, velocidade e custo. + + + +## Configurando seu LLM + +Existem diferentes locais no código do CrewAI onde você pode especificar o modelo a ser utilizado. Após definir o modelo usado, será necessário fornecer a configuração (como uma chave de API) para cada provedor de modelo. Veja a seção de [exemplos de configuração de provedores](#provider-configuration-examples) para seu provedor. + + + + A maneira mais simples de começar. Defina o modelo diretamente em seu ambiente, usando um arquivo `.env` ou no código do seu aplicativo. Se você utilizou `crewai create` para iniciar seu projeto, já estará configurado. + + ```bash .env + MODEL=model-id # e.g. gpt-4o, gemini-2.0-flash, claude-3-sonnet-... + + # Lembre-se de definir suas chaves de API aqui também. Veja a seção + # do Provedor abaixo. + ``` + + + Nunca envie chaves de API para controle de versão. Use arquivos de ambiente (.env) ou o gerenciamento de segredos do seu sistema. + + + + Crie um arquivo YAML para definir as configurações dos seus agentes. Este método é ótimo para controle de versão e colaboração em equipe: + + ```yaml agents.yaml {6} + researcher: + role: Research Specialist + goal: Conduct comprehensive research and analysis + backstory: A dedicated research professional with years of experience + verbose: true + llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude... + # (veja exemplos de configuração de provedores abaixo para mais) + ``` + + + A configuração YAML permite: + - Controlar versões das configurações dos agentes + - Trocar facilmente entre diferentes modelos + - Compartilhar configurações entre membros da equipe + - Documentar escolhas de modelos e seus propósitos + + + + Para máxima flexibilidade, configure os LLMs diretamente no seu código Python: + + ```python {4,8} + from crewai import LLM + + # Configuração básica + llm = LLM(model="model-id-here") # gpt-4o, gemini-2.0-flash, anthropic/claude... + + # Configuração avançada com parâmetros detalhados + llm = LLM( + model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude... + temperature=0.7, # Mais alto para saídas criativas + timeout=120, # Segundos para aguardar resposta + max_tokens=4000, # Comprimento máximo da resposta + top_p=0.9, # Parâmetro de amostragem nucleus + frequency_penalty=0.1 , # Reduz repetição + presence_penalty=0.1, # Incentiva diversidade de tópicos + response_format={"type": "json"}, # Para respostas estruturadas + seed=42 # Para resultados reproduzíveis + ) + ``` + + + Explicações dos parâmetros: + - `temperature`: Controla a aleatoriedade (0.0-1.0) + - `timeout`: Tempo máximo de espera pela resposta + - `max_tokens`: Limita o comprimento da resposta + - `top_p`: Alternativa à temperatura para amostragem + - `frequency_penalty`: Reduz repetição de palavras + - `presence_penalty`: Incentiva novos tópicos + - `response_format`: Especifica formato de saída + - `seed`: Garante resultados consistentes + + + + +## Exemplos de Configuração de Provedores + +O CrewAI suporta uma grande variedade de provedores de LLM, cada um com recursos, métodos de autenticação e capacidades de modelo únicos. +Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, configurar e otimizar o LLM que melhor atende às necessidades do seu projeto. + + + + Defina as seguintes variáveis de ambiente no seu arquivo `.env`: + + ```toml Code + # Obrigatório + OPENAI_API_KEY=sk-... + + # Opcional + OPENAI_API_BASE= + OPENAI_ORGANIZATION= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + from crewai import LLM + + llm = LLM( + model="openai/gpt-4", # chamar modelo por provider/model_name + temperature=0.8, + max_tokens=150, + top_p=0.9, + frequency_penalty=0.1, + presence_penalty=0.1, + stop=["END"], + seed=42 + ) + ``` + + OpenAI é um dos líderes em modelos LLM com uma ampla gama de modelos e recursos. + + | Modelo | Janela de Contexto | Melhor Para | + |----------------------|---------------------|------------------------------------------| + | GPT-4 | 8.192 tokens | Tarefas de alta precisão, raciocínio complexo | + | GPT-4 Turbo | 128.000 tokens | Conteúdo longo, análise de documentos | + | GPT-4o & GPT-4o-mini | 128.000 tokens | Processamento de contexto amplo com bom custo-benefício | + | o3-mini | 200.000 tokens | Raciocínio rápido, tarefas complexas | + | o1-mini | 128.000 tokens | Raciocínio rápido, tarefas complexas | + | o1-preview | 128.000 tokens | Raciocínio rápido, tarefas complexas | + | o1 | 200.000 tokens | Raciocínio rápido, tarefas complexas | + + + + A API Llama da Meta fornece acesso à família de modelos de linguagem de grande escala da Meta. + A API está disponível através da [Meta Llama API](https://llama.developer.meta.com?utm_source=partner-crewai&utm_medium=website). + Defina as seguintes variáveis de ambiente no seu arquivo `.env`: + + ```toml Code + # Configuração chave da API Meta Llama + LLAMA_API_KEY=LLM|your_api_key_here + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + from crewai import LLM + + # Inicializar Meta Llama LLM + llm = LLM( + model="meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8", + temperature=0.8, + stop=["END"], + seed=42 + ) + ``` + + Todos os modelos listados em https://llama.developer.meta.com/docs/models/ são suportados. + + | ID do Modelo | Comprimento contexto entrada | Comprimento contexto saída | Modalidades de entrada | Modalidades de saída | + | --- | --- | --- | --- | --- | + | `meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8` | 128k | 4028 | Texto, Imagem | Texto | + | `meta_llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 128k | 4028 | Texto, Imagem | Texto | + | `meta_llama/Llama-3.3-70B-Instruct` | 128k | 4028 | Texto | Texto | + | `meta_llama/Llama-3.3-8B-Instruct` | 128k | 4028 | Texto | Texto | + + + + ```toml Code + # Obrigatório + ANTHROPIC_API_KEY=sk-ant-... + + # Opcional + ANTHROPIC_API_BASE= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="anthropic/claude-3-sonnet-20240229-v1:0", + temperature=0.7 + ) + ``` + + + + Defina sua chave de API no seu arquivo `.env`. Se precisar de uma chave, ou encontrar uma existente, verifique o [AI Studio](https://aistudio.google.com/apikey). + + ```toml .env + # https://ai.google.dev/gemini-api/docs/api-key + GEMINI_API_KEY= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.0-flash", + temperature=0.7, + ) + ``` + + ### Modelos Gemini + + O Google oferece uma variedade de modelos poderosos otimizados para diferentes casos de uso. + + | Modelo | Janela de Contexto | Melhor Para | + |----------------------------------|--------------------|---------------------------------------------------------------------| + | gemini-2.5-flash-preview-04-17 | 1M tokens | Pensamento adaptativo, eficiência de custo | + | gemini-2.5-pro-preview-05-06 | 1M tokens | Pensamento e raciocínio avançados, compreensão multimodal, codificação avançada, etc. | + | gemini-2.0-flash | 1M tokens | Próxima geração de recursos, velocidade, raciocínio e streaming em tempo real | + | gemini-2.0-flash-lite | 1M tokens | Eficiência de custo e baixa latência | + | gemini-1.5-flash | 1M tokens | Modelo multimodal equilibrado, bom para maioria das tarefas | + | gemini-1.5-flash-8B | 1M tokens | Mais rápido, mais eficiente em custo, adequado para tarefas de alta frequência | + | gemini-1.5-pro | 2M tokens | Melhor desempenho para uma ampla variedade de tarefas de raciocínio, incluindo lógica, codificação e colaboração criativa | + + A lista completa de modelos está disponível na [documentação dos modelos Gemini](https://ai.google.dev/gemini-api/docs/models). + + ### Gemma + + A API Gemini também permite uso de sua chave de API para acessar [modelos Gemma](https://ai.google.dev/gemma/docs) hospedados na infraestrutura Google. + + | Modelo | Janela de Contexto | + |----------------|-------------------| + | gemma-3-1b-it | 32k tokens | + | gemma-3-4b-it | 32k tokens | + | gemma-3-12b-it | 32k tokens | + | gemma-3-27b-it | 128k tokens | + + + + Obtenha as credenciais pelo Google Cloud Console, salve em um arquivo JSON e carregue com o código a seguir: + ```python Code + import json + + file_path = 'path/to/vertex_ai_service_account.json' + + # Carregar o arquivo JSON + with open(file_path, 'r') as file: + vertex_credentials = json.load(file) + + # Converter credenciais em string JSON + vertex_credentials_json = json.dumps(vertex_credentials) + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-1.5-pro-latest", + temperature=0.7, + vertex_credentials=vertex_credentials_json + ) + ``` + + O Google oferece uma variedade de modelos poderosos otimizados para diferentes casos de uso: + + | Modelo | Janela de Contexto | Melhor Para | + |----------------------------------|--------------------|---------------------------------------------------------------------| + | gemini-2.5-flash-preview-04-17 | 1M tokens | Pensamento adaptativo, eficiência de custo | + | gemini-2.5-pro-preview-05-06 | 1M tokens | Pensamento e raciocínio avançados, compreensão multimodal, codificação avançada, etc. | + | gemini-2.0-flash | 1M tokens | Próxima geração de recursos, velocidade, raciocínio e streaming em tempo real | + | gemini-2.0-flash-lite | 1M tokens | Eficiência de custo e baixa latência | + | gemini-1.5-flash | 1M tokens | Modelo multimodal equilibrado, bom para maioria das tarefas | + | gemini-1.5-flash-8B | 1M tokens | Mais rápido, mais eficiente em custo, adequado para tarefas de alta frequência | + | gemini-1.5-pro | 2M tokens | Melhor desempenho para uma ampla variedade de tarefas de raciocínio, incluindo lógica, codificação e colaboração criativa | + + + + ```toml Code + # Obrigatório + AZURE_API_KEY= + AZURE_API_BASE= + AZURE_API_VERSION= + + # Opcional + AZURE_AD_TOKEN= + AZURE_API_TYPE= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="azure/gpt-4", + api_version="2023-05-15" + ) + ``` + + + + ```toml Code + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + AWS_DEFAULT_REGION= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="bedrock/anthropic.claude-3-sonnet-20240229-v1:0" + ) + ``` + + Antes de usar o Amazon Bedrock, certifique-se de ter o boto3 instalado em seu ambiente + + [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) é um serviço gerenciado que fornece acesso a múltiplos modelos fundamentais dos principais provedores de IA através de uma API unificada, permitindo o desenvolvimento seguro e responsável de aplicações de IA. + + | Modelo | Janela de Contexto | Melhor Para | + |--------------------------|------------------------|---------------------------------------------------------------------| + | Amazon Nova Pro | Até 300k tokens | Alto desempenho, equilíbrio entre precisão, velocidade e custo em tarefas diversas. | + | Amazon Nova Micro | Até 128k tokens | Modelo texto-only de alta performance, custo-benefício, otimizado para baixa latência. | + | Amazon Nova Lite | Até 300k tokens | Alto desempenho, processamento multimodal acessível para texto, imagem, vídeo em tempo real. | + | Claude 3.7 Sonnet | Até 128k tokens | Alto desempenho para raciocínio complexo, programação & agentes de IA| + | Claude 3.5 Sonnet v2 | Até 200k tokens | Modelo avançado especializado em engenharia de software, capacidades agenticas e interação computacional com custo otimizado. | + | Claude 3.5 Sonnet | Até 200k tokens | Alto desempenho com inteligência e raciocínio excepcionais, equilíbrio entre velocidade-custo. | + | Claude 3.5 Haiku | Até 200k tokens | Modelo multimodal rápido e compacto, otimizado para respostas rápidas e interações humanas naturais | + | Claude 3 Sonnet | Até 200k tokens | Modelo multimodal equilibrando inteligência e velocidade para grandes volumes de uso. | + | Claude 3 Haiku | Até 200k tokens | Compacto, multimodal, otimizado para respostas rápidas e diálogo natural | + | Claude 3 Opus | Até 200k tokens | Modelo multimodal mais avançado para tarefas complexas com raciocínio humano e entendimento contextual superior. | + | Claude 2.1 | Até 200k tokens | Versão aprimorada com janela de contexto aumentada, maior confiabilidade, menos alucinações para aplicações longas e RAG | + | Claude | Até 100k tokens | Modelo versátil para diálogos sofisticados, conteúdo criativo e instruções precisas. | + | Claude Instant | Até 100k tokens | Modelo rápido e de baixo custo para tarefas diárias, como diálogos, análise, sumarização e Q&A em documentos | + | Llama 3.1 405B Instruct | Até 128k tokens | LLM avançado para geração de dados sintéticos, distilação e inferência para chatbots, programação, tarefas de domínio específico. | + | Llama 3.1 70B Instruct | Até 128k tokens | Potencializa conversas complexas com entendimento contextual superior, raciocínio e geração de texto. | + | Llama 3.1 8B Instruct | Até 128k tokens | Modelo de última geração, entendimento de linguagem, raciocínio e geração de texto. | + | Llama 3 70B Instruct | Até 8k tokens | Potencializa conversas complexas com entendimento contextual superior, raciocínio e geração de texto. | + | Llama 3 8B Instruct | Até 8k tokens | LLM de última geração com excelente desempenho em linguagem e geração de texto. | + | Titan Text G1 - Lite | Até 4k tokens | Modelo leve e econômico para tarefas em inglês e ajuste fino, focado em sumarização e geração de conteúdo. | + | Titan Text G1 - Express | Até 8k tokens | Modelo versátil para tarefas gerais de linguagem, chat e aplicações RAG com suporte a inglês e 100+ línguas. | + | Cohere Command | Até 4k tokens | Modelo especializado em seguir comandos do usuário e entregar soluções empresariais práticas. | + | Jurassic-2 Mid | Até 8.191 tokens | Modelo econômico equilibrando qualidade e custo para tarefas como Q&A, sumarização e geração de conteúdo. | + | Jurassic-2 Ultra | Até 8.191 tokens | Geração avançada de texto e compreensão, excelente em análise e criação de conteúdo complexo. | + | Jamba-Instruct | Até 256k tokens | Modelo com janela de contexto extendida para geração de texto, sumarização e Q&A de baixo custo. | + | Mistral 7B Instruct | Até 32k tokens | LLM atende instruções, solicitações e gera texto criativo. | + | Mistral 8x7B Instruct | Até 32k tokens | MOE LLM que atende instruções, solicitações e gera texto criativo. | + + + + ```toml Code + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + AWS_DEFAULT_REGION= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="sagemaker/" + ) + ``` + + + + Defina as seguintes variáveis de ambiente no seu arquivo `.env`: + ```toml Code + MISTRAL_API_KEY= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="mistral/mistral-large-latest", + temperature=0.7 + ) + ``` + + + + Defina as seguintes variáveis de ambiente no seu arquivo `.env`: + ```toml Code + NVIDIA_API_KEY= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="nvidia_nim/meta/llama3-70b-instruct", + temperature=0.7 + ) + ``` + + O Nvidia NIM oferece uma suíte abrangente de modelos para diversos usos, desde tarefas gerais até aplicações especializadas. + + | Modelo | Janela de Contexto | Melhor Para | + |--------------------------------------------------------------------------|--------------------|---------------------------------------------------------------------| + | nvidia/mistral-nemo-minitron-8b-8k-instruct | 8.192 tokens | Modelo pequeno de linguagem topo de linha para chatbots, assistentes virtuais e geração de conteúdo. | + | nvidia/nemotron-4-mini-hindi-4b-instruct | 4.096 tokens | SLM bilíngue Hindi-Inglês para inferência no dispositivo, específico para língua hindi. | + | nvidia/llama-3.1-nemotron-70b-instruct | 128k tokens | Personalizado para respostas mais úteis | + | nvidia/llama3-chatqa-1.5-8b | 128k tokens | LLM avançado para respostas contextuais de alta qualidade em chatbots e mecanismos de busca. | + | nvidia/llama3-chatqa-1.5-70b | 128k tokens | LLM avançado para respostas contextuais de alta qualidade para chatbots e mecanismos de busca. | + | nvidia/vila | 128k tokens | Modelo multmodal visão-linguagem para compreensão de texto/img/vídeo com respostas informativas | + | nvidia/neva-22 | 4.096 tokens | Modelo de visão-linguagem multimodal para compreensão textos/imagens e respostas informativas | + | nvidia/nemotron-mini-4b-instruct | 8.192 tokens | Tarefas gerais | + | nvidia/usdcode-llama3-70b-instruct | 128k tokens | LLM de ponta para queries OpenUSD e geração de código USD-Python. | + | nvidia/nemotron-4-340b-instruct | 4.096 tokens | Gera dados sintéticos diversos simulando características reais. | + | meta/codellama-70b | 100k tokens | LLM capaz de gerar código a partir de linguagem natural e vice-versa.| + | meta/llama2-70b | 4.096 tokens | Modelo de IA avançado para geração de textos e códigos. | + | meta/llama3-8b-instruct | 8.192 tokens | LLM de última geração, entendimento de linguagem, raciocínio e geração de texto. | + | meta/llama3-70b-instruct | 8.192 tokens | Potencializa conversas complexas com entendimento contextual superior, raciocínio e geração de texto.| + | meta/llama-3.1-8b-instruct | 128k tokens | Modelo compacto de última geração, com compreensão, raciocínio e geração de texto superior. | + | meta/llama-3.1-70b-instruct | 128k tokens | Potencializa conversas complexas com entendimento contextual superior, raciocínio e geração de texto. | + | meta/llama-3.1-405b-instruct | 128k tokens | LLM avançado para geração sintética de dados, destilação e inferência para chatbots, código, tarefas de domínio específico. | + | meta/llama-3.2-1b-instruct | 128k tokens | Pequeno modelo de linguagem de última geração, entendimento, raciocínio e geração textual.| + | meta/llama-3.2-3b-instruct | 128k tokens | Pequeno modelo de linguagem de última geração, entendimento, raciocínio e geração textual.| + | meta/llama-3.2-11b-vision-instruct | 128k tokens | Pequeno modelo de linguagem de última geração, entendimento, raciocínio e geração textual multimodal.| + | meta/llama-3.2-90b-vision-instruct | 128k tokens | Pequeno modelo de linguagem de última geração, entendimento, raciocínio e geração textual multimodal.| + | google/gemma-7b | 8.192 tokens | Modelo avançado de geração de texto, compreensão, transformação e programação.| + | google/gemma-2b | 8.192 tokens | Modelo avançado de geração de texto, compreensão, transformação e programação.| + | google/codegemma-7b | 8.192 tokens | Modelo avançado baseado no Gemma-7B do Google, especializado em geração de códigos e autocomplete.| + | google/codegemma-1.1-7b | 8.192 tokens | Modelo avançado para geração, complemento, raciocínio e instrução em código.| + | google/recurrentgemma-2b | 8.192 tokens | Modelo baseado em arquitetura recorrente para inferência mais rápida em sequências longas.| + | google/gemma-2-9b-it | 8.192 tokens | Modelo avançado de geração de texto, compreensão, transformação e programação.| + | google/gemma-2-27b-it | 8.192 tokens | Modelo avançado de geração de texto, compreensão, transformação e programação.| + | google/gemma-2-2b-it | 8.192 tokens | Modelo avançado de geração de texto, compreensão, transformação e programação.| + | google/deplot | 512 tokens | Modelo visual por linguagem para entender gráficos e converter em tabelas.| + | google/paligemma | 8.192 tokens | Modelo visão-linguagem experto em compreender texto e visual, gerando respostas informativas.| + | mistralai/mistral-7b-instruct-v0.2 | 32k tokens | LLM que segue instruções, completa pedidos e gera texto criativo. | + | mistralai/mixtral-8x7b-instruct-v0.1 | 8.192 tokens | MOE LLM para seguir instruções e gerar versões criativas de texto. | + | mistralai/mistral-large | 4.096 tokens | Geração de dados sintéticos. | + | mistralai/mixtral-8x22b-instruct-v0.1 | 8.192 tokens | Geração de dados sintéticos. | + | mistralai/mistral-7b-instruct-v0.3 | 32k tokens | LLM que segue instruções, completa pedidos e gera texto criativo. | + | nv-mistralai/mistral-nemo-12b-instruct | 128k tokens | Modelo de linguagem avançado para raciocínio, código, tarefas multilíngues; roda em uma única GPU.| + | mistralai/mamba-codestral-7b-v0.1 | 256k tokens | Modelo para escrita e interação com código em múltiplas linguagens e tarefas.| + | microsoft/phi-3-mini-128k-instruct | 128K tokens | LLM leve, de última geração, com habilidades de lógica e matemática.| + | microsoft/phi-3-mini-4k-instruct | 4.096 tokens | LLM leve, de última geração, com habilidades de lógica e matemática.| + | microsoft/phi-3-small-8k-instruct | 8.192 tokens | LLM leve, de última geração, com habilidades de lógica e matemática.| + | microsoft/phi-3-small-128k-instruct | 128K tokens | LLM leve, de última geração, com habilidades de lógica e matemática.| + | microsoft/phi-3-medium-4k-instruct | 4.096 tokens | LLM leve, de última geração, com habilidades de lógica e matemática.| + | microsoft/phi-3-medium-128k-instruct | 128K tokens | LLM leve, de última geração, com habilidades de lógica e matemática.| + | microsoft/phi-3.5-mini-instruct | 128K tokens | LLM multilíngue leve para aplicações de IA restritas em memória e tempo.| + | microsoft/phi-3.5-moe-instruct | 128K tokens | LLM avançada baseada em Mixture of Experts para geração eficiente de conteúdo.| + | microsoft/kosmos-2 | 1.024 tokens | Modelo multimodal revolucionário para compreender e raciocinar elementos visuais em imagens.| + | microsoft/phi-3-vision-128k-instruct | 128k tokens | Modelo multimodal aberto de ponta para raciocínio de alta qualidade a partir de imagens.| + | microsoft/phi-3.5-vision-instruct | 128k tokens | Modelo multimodal aberto de ponta para raciocínio de alta qualidade a partir de imagens.| + | databricks/dbrx-instruct | 12k tokens | LLM de uso geral com desempenho no estado da arte para linguagem, programação e RAG.| + | snowflake/arctic | 1.024 tokens | Inferência eficiente para aplicações empresariais focadas em SQL e programação.| + | aisingapore/sea-lion-7b-instruct | 4.096 tokens | LLM para representação e diversidade linguística e cultural do sudeste asiático.| + | ibm/granite-8b-code-instruct | 4.096 tokens | LLM para programação: geração, explicação e diálogo multi-turn de código.| + | ibm/granite-34b-code-instruct | 8.192 tokens | LLM para programação: geração, explicação e diálogo multi-turn de código.| + | ibm/granite-3.0-8b-instruct | 4.096 tokens | Pequeno modelo avançado, com suporte a RAG, sumário, classificação, código e IA agentica.| + | ibm/granite-3.0-3b-a800m-instruct | 4.096 tokens | Modelo Mixture of Experts eficiente para RAG, sumário, extração de entidades, classificação.| + | mediatek/breeze-7b-instruct | 4.096 tokens | Gera dados sintéticos diversos.| + | upstage/solar-10.7b-instruct | 4.096 tokens | Excelente em tarefas de PLN, especialmente seguir instruções, raciocínio e matemática.| + | writer/palmyra-med-70b-32k | 32k tokens | LLM líder para respostas médicas precisas e contextuais.| + | writer/palmyra-med-70b | 32k tokens | LLM líder para respostas médicas precisas e contextuais.| + | writer/palmyra-fin-70b-32k | 32k tokens | LLM especializada em análise financeira, relatórios e processamento de dados.| + | 01-ai/yi-large | 32k tokens | Poderoso para inglês e chinês, incluindo chatbot e escrita criativa.| + | deepseek-ai/deepseek-coder-6.7b-instruct | 2k tokens | Modelo avançado para geração de código, autocomplete, infilling.| + | rakuten/rakutenai-7b-instruct | 1.024 tokens | LLM topo de linha, compreensão, raciocínio e geração textual.| + | rakuten/rakutenai-7b-chat | 1.024 tokens | LLM topo de linha, compreensão, raciocínio e geração textual.| + | baichuan-inc/baichuan2-13b-chat | 4.096 tokens | Suporte a chat em chinês/inglês, programação, matemática, seguir instruções, resolver quizzes.| + + + + + O NVIDIA NIM permite rodar LLMs potentes localmente em máquinas Windows usando WSL2 (Windows Subsystem for Linux). + Este método aproveita o GPU NVIDIA para inferência privativa, segura e econômica, sem depender de serviços em nuvem. + Perfeito para desenvolvimento, testes ou produção onde privacidade ou funcionalidades offline são necessárias. + + Aqui está um guia passo a passo para configurar um modelo local NVIDIA NIM: + + 1. Siga as instruções de instalação no [site da NVIDIA](https://docs.nvidia.com/nim/wsl2/latest/getting-started.html) + + 2. Instale o modelo local. Para Llama 3.1-8b siga as [instruções](https://build.nvidia.com/meta/llama-3_1-8b-instruct/deploy) + + 3. Configure seus modelos locais crewai: + + ```python Code + from crewai.llm import LLM + + local_nvidia_nim_llm = LLM( + model="openai/meta/llama-3.1-8b-instruct", # é compatível com openai-api + base_url="http://localhost:8000/v1", + api_key="", # api_key obrigatório, pode usar qualquer texto + ) + + # Então pode usá-lo no seu crew: + + @CrewBase + class MyCrew(): + # ... + + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], # type: ignore[index] + llm=local_nvidia_nim_llm + ) + + # ... + ``` + + + + Defina as seguintes variáveis de ambiente no seu arquivo `.env`: + + ```toml Code + GROQ_API_KEY= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="groq/llama-3.2-90b-text-preview", + temperature=0.7 + ) + ``` + | Modelo | Janela de Contexto | Melhor Para | + |-------------------|---------------------|------------------------------------------| + | Llama 3.1 70B/8B | 131.072 tokens | Alta performance e tarefas de contexto grande| + | Llama 3.2 Série | 8.192 tokens | Tarefas gerais | + | Mixtral 8x7B | 32.768 tokens | Equilíbrio entre performance e contexto | + + + + Defina as seguintes variáveis de ambiente no seu arquivo `.env`: + ```toml Code + # Obrigatório + WATSONX_URL= + WATSONX_APIKEY= + WATSONX_PROJECT_ID= + + # Opcional + WATSONX_TOKEN= + WATSONX_DEPLOYMENT_SPACE_ID= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="watsonx/meta-llama/llama-3-1-70b-instruct", + base_url="https://api.watsonx.ai/v1" + ) + ``` + + + + 1. Instale o Ollama: [ollama.ai](https://ollama.ai/) + 2. Rode um modelo: `ollama run llama3` + 3. Configure: + + ```python Code + llm = LLM( + model="ollama/llama3:70b", + base_url="http://localhost:11434" + ) + ``` + + + + Defina as seguintes variáveis de ambiente no seu arquivo `.env`: + ```toml Code + FIREWORKS_API_KEY= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="fireworks_ai/accounts/fireworks/models/llama-v3-70b-instruct", + temperature=0.7 + ) + ``` + + + + Defina as seguintes variáveis de ambiente no seu arquivo `.env`: + ```toml Code + PERPLEXITY_API_KEY= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="llama-3.1-sonar-large-128k-online", + base_url="https://api.perplexity.ai/" + ) + ``` + + + + Defina as seguintes variáveis de ambiente no seu arquivo `.env`: + ```toml Code + HF_TOKEN= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="huggingface/meta-llama/Meta-Llama-3.1-8B-Instruct" + ) + ``` + + + + Defina as seguintes variáveis de ambiente no seu arquivo `.env`: + + ```toml Code + SAMBANOVA_API_KEY= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="sambanova/Meta-Llama-3.1-8B-Instruct", + temperature=0.7 + ) + ``` + | Modelo | Janela de Contexto | Melhor Para | + |-------------------|---------------------------|----------------------------------------------| + | Llama 3.1 70B/8B | Até 131.072 tokens | Alto desempenho, tarefas com grande contexto | + | Llama 3.1 405B | 8.192 tokens | Desempenho e qualidade de saída elevada | + | Llama 3.2 Série | 8.192 tokens | Tarefas gerais e multimodais | + | Llama 3.3 70B | Até 131.072 tokens | Desempenho e qualidade de saída elevada | + | Família Qwen2 | 8.192 tokens | Desempenho e qualidade de saída elevada | + + + + Defina as seguintes variáveis de ambiente no seu arquivo `.env`: + ```toml Code + # Obrigatório + CEREBRAS_API_KEY= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="cerebras/llama3.1-70b", + temperature=0.7, + max_tokens=8192 + ) + ``` + + + Recursos do Cerebras: + - Altas velocidades de inferência + - Preços competitivos + - Equilíbrio entre velocidade e qualidade + - Suporte a longas janelas de contexto + + + + + Defina as seguintes variáveis de ambiente no seu arquivo `.env`: + ```toml Code + OPENROUTER_API_KEY= + ``` + + Exemplo de uso em seu projeto CrewAI: + ```python Code + llm = LLM( + model="openrouter/deepseek/deepseek-r1", + base_url="https://openrouter.ai/api/v1", + api_key=OPENROUTER_API_KEY + ) + ``` + + + Modelos do Open Router: + - openrouter/deepseek/deepseek-r1 + - openrouter/deepseek/deepseek-chat + + + + +## Respostas em streaming + +O CrewAI suporta respostas em streaming de LLMs, permitindo que sua aplicação receba e processe saídas em tempo real assim que são geradas. + + + + Ative o streaming definindo o parâmetro `stream` como `True` ao inicializar seu LLM: + + ```python + from crewai import LLM + + # Crie um LLM com streaming ativado + llm = LLM( + model="openai/gpt-4o", + stream=True # Ativar streaming + ) + ``` + + Quando o streaming está ativado, as respostas são entregues em partes à medida que vão sendo geradas, criando uma experiência mais responsiva para o usuário. + + + + O CrewAI emite eventos para cada chunk recebido durante o streaming: + + ```python + from crewai.utilities.events import ( + LLMStreamChunkEvent + ) + from crewai.utilities.events.base_event_listener import BaseEventListener + + class MyCustomListener(BaseEventListener): + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(LLMStreamChunkEvent) + def on_llm_stream_chunk(self, event: LLMStreamChunkEvent): + # Clique para cada chunk assim que chegar + print(f"Received chunk: {event.chunk}") + + my_listener = MyCustomListener() + ``` + + + [Clique aqui](https://docs.crewai.com/concepts/event-listener#event-listeners) para mais detalhes + + + + +## Chamada Estruturada de LLM + +O CrewAI suporta respostas estruturadas de LLMs permitindo que você defina um `response_format` usando um modelo Pydantic. Isso permite que o framework automaticamente faça o parsing e valide a saída, facilitando a integração da resposta em sua aplicação sem pós-processamento manual. + +Por exemplo, é possível definir um modelo Pydantic para representar a resposta esperada e passá-lo como `response_format` ao instanciar o LLM. O modelo será utilizado para converter a resposta do LLM em um objeto Python estruturado. + +```python Code +from crewai import LLM + +class Dog(BaseModel): + name: str + age: int + breed: str + + +llm = LLM(model="gpt-4o", response_format=Dog) + +response = llm.call( + "Analyze the following messages and return the name, age, and breed. " + "Meet Kona! She is 3 years old and is a black german shepherd." +) +print(response) + +# Output: +# Dog(name='Kona', age=3, breed='black german shepherd') +``` + +## Recursos Avançados e Otimização + +Saiba como obter o máximo da configuração do seu LLM: + + + + O CrewAI inclui recursos inteligentes para gerenciamento de contexto: + + ```python + from crewai import LLM + + # O CrewAI automaticamente gerencia: + # 1. Contagem e acompanhamento de tokens + # 2. Resumo de conteúdo quando necessário + # 3. Divisão de tarefas para grandes contextos + + llm = LLM( + model="gpt-4", + max_tokens=4000, # Limitar tamanho da resposta + ) + ``` + + + Boas práticas para o gerenciamento de contexto: + 1. Prefira modelos com janelas apropriadas + 2. Pré-processe entradas muito longas + 3. Utilize divisão para documentos grandes + 4. Monitore tokens para otimizar custos + + + + + + + Escolha a janela de contexto certa para sua tarefa: + - Tarefas pequenas (até 4K tokens): Modelos padrão + - Tarefas médias (entre 4K-32K): Modelos aprimorados + - Tarefas grandes (acima de 32K): Modelos com contexto expandido + + ```python + # Configure o modelo com as opções certas + llm = LLM( + model="openai/gpt-4-turbo-preview", + temperature=0.7, # Ajuste conforme a tarefa + max_tokens=4096, # Defina conforme a necessidade da saída + timeout=300 # Timeout maior para tarefas complexas + ) + ``` + + - Temperaturas baixas (0.1 a 0.3) para respostas factuais + - Temperaturas altas (0.7 a 0.9) para tarefas criativas + + + + + 1. Monitore o uso de tokens + 2. Implemente limites de taxa (rate limiting) + 3. Use cache quando possível + 4. Defina limites apropriados para max_tokens + + + + + Lembre-se de monitorar regularmente o uso de tokens e ajustar suas configurações para otimizar custos e desempenho. + + + + + O CrewAI usa Litellm internamente para chamadas LLM, permitindo descartar parâmetros adicionais desnecessários para seu caso de uso. Isso pode simplificar seu código e reduzir a complexidade da configuração do LLM. + Por exemplo, se não precisar enviar o parâmetro stop, basta omiti-lo na chamada do LLM: + + ```python + from crewai import LLM + import os + + os.environ["OPENAI_API_KEY"] = "" + + o3_llm = LLM( + model="o3", + drop_params=True, + additional_drop_params=["stop"] + ) + ``` + + + +## Problemas Comuns e Soluções + + + + + A maioria dos problemas de autenticação pode ser resolvida verificando o formato da chave da API e os nomes das variáveis de ambiente. + + + ```bash + # OpenAI + OPENAI_API_KEY=sk-... + + # Anthropic + ANTHROPIC_API_KEY=sk-ant-... + ``` + + + + Sempre inclua o prefixo do provedor nos nomes dos modelos + + + ```python + # Correto + llm = LLM(model="openai/gpt-4") + + # Incorreto + llm = LLM(model="gpt-4") + ``` + + + + Use modelos de contexto expandido para tarefas extensas + + + ```python + # Modelo com contexto expandido + llm = LLM(model="openai/gpt-4o") # 128K tokens + ``` + + \ No newline at end of file diff --git a/docs/pt-BR/concepts/memory.mdx b/docs/pt-BR/concepts/memory.mdx new file mode 100644 index 000000000..ff498d312 --- /dev/null +++ b/docs/pt-BR/concepts/memory.mdx @@ -0,0 +1,992 @@ +--- +title: Memória +description: Aproveitando sistemas de memória no framework CrewAI para aprimorar as capacidades dos agentes. +icon: database +--- + +## Visão Geral + +O framework CrewAI oferece um sistema de memória sofisticado projetado para aprimorar significativamente as capacidades dos agentes de IA. O CrewAI disponibiliza **três abordagens distintas de memória** que atendem a diferentes casos de uso: + +1. **Sistema Básico de Memória** - Memória de curto prazo, longo prazo e de entidades integradas +2. **Memória de Usuário** - Memória específica do usuário com integração ao Mem0 (abordagem legada) +3. **Memória Externa** - Provedores de memória externos autônomos (nova abordagem) + +## Componentes do Sistema de Memória + +| Componente | Descrição | +| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Memória de Curto Prazo** | Armazena temporariamente interações e resultados recentes usando `RAG`, permitindo que os agentes recordem e utilizem informações relevantes ao contexto atual durante as execuções. | +| **Memória de Longo Prazo** | Preserva informações valiosas e aprendizados de execuções passadas, permitindo que os agentes construam e refinem seu conhecimento ao longo do tempo. | +| **Memória de Entidades** | Captura e organiza informações sobre entidades (pessoas, lugares, conceitos) encontradas durante tarefas, facilitando um entendimento mais profundo e o mapeamento de relacionamentos. Utiliza `RAG` para armazenar informações de entidades. | +| **Memória Contextual** | Mantém o contexto das interações combinando `ShortTermMemory`, `LongTermMemory` e `EntityMemory`, auxiliando na coerência e relevância das respostas dos agentes ao longo de uma sequência de tarefas ou conversas. | + +## 1. Sistema Básico de Memória (Recomendado) + +A abordagem mais simples e comum de uso. Ative a memória para sua crew com um único parâmetro: + +### Início Rápido +```python +from crewai import Crew, Agent, Task, Process + +# Habilitar o sistema básico de memória +crew = Crew( + agents=[...], + tasks=[...], + process=Process.sequential, + memory=True, # Ativa memória de curto prazo, longo prazo e de entidades + verbose=True +) +``` + +### Como Funciona +- **Memória de Curto Prazo**: Usa ChromaDB com RAG para o contexto atual +- **Memória de Longo Prazo**: Usa SQLite3 para armazenar resultados de tarefas entre sessões +- **Memória de Entidades**: Usa RAG para rastrear entidades (pessoas, lugares, conceitos) +- **Local de Armazenamento**: Localidade específica da plataforma via pacote `appdirs` +- **Diretório de Armazenamento Personalizado**: Defina a variável de ambiente `CREWAI_STORAGE_DIR` + +## Transparência no Local de Armazenamento + + +**Compreendendo os Locais de Armazenamento**: CrewAI utiliza diretórios específicos da plataforma para guardar arquivos de memória e conhecimento seguindo as convenções do sistema operacional. Conhecer esses locais ajuda na implantação em produção, backups e depuração. + + +### Onde o CrewAI Armazena os Arquivos + +Por padrão, o CrewAI usa a biblioteca `appdirs` para determinar os locais de armazenamento conforme a convenção da plataforma. Veja exatamente onde seus arquivos são armazenados: + +#### Locais de Armazenamento Padrão por Plataforma + +**macOS:** +``` +~/Library/Application Support/CrewAI/{project_name}/ +├── knowledge/ # Arquivos base de conhecimento ChromaDB +├── short_term_memory/ # Arquivos de memória de curto prazo ChromaDB +├── long_term_memory/ # Arquivos de memória de longo prazo ChromaDB +├── entities/ # Arquivos de memória de entidades ChromaDB +└── long_term_memory_storage.db # Banco de dados SQLite +``` + +**Linux:** +``` +~/.local/share/CrewAI/{project_name}/ +├── knowledge/ +├── short_term_memory/ +├── long_term_memory/ +├── entities/ +└── long_term_memory_storage.db +``` + +**Windows:** +``` +C:\Users\{username}\AppData\Local\CrewAI\{project_name}\ +├── knowledge\ +├── short_term_memory\ +├── long_term_memory\ +├── entities\ +└── long_term_memory_storage.db +``` + +### Encontrando Seu Local de Armazenamento + +Para ver exatamente onde o CrewAI está armazenando arquivos em seu sistema: + +```python +from crewai.utilities.paths import db_storage_path +import os + +# Obter o caminho base de armazenamento +storage_path = db_storage_path() +print(f"CrewAI storage location: {storage_path}") + +# Listar todos os diretórios e arquivos do CrewAI +if os.path.exists(storage_path): + print("\nStored files and directories:") + for item in os.listdir(storage_path): + item_path = os.path.join(storage_path, item) + if os.path.isdir(item_path): + print(f"📁 {item}/") + # Exibir coleções ChromaDB + if os.path.exists(item_path): + for subitem in os.listdir(item_path): + print(f" └── {subitem}") + else: + print(f"📄 {item}") +else: + print("No CrewAI storage directory found yet.") +``` + +### Controlando Locais de Armazenamento + +#### Opção 1: Variável de Ambiente (Recomendado) +```python +import os +from crewai import Crew + +# Definir local de armazenamento personalizado +os.environ["CREWAI_STORAGE_DIR"] = "./my_project_storage" + +# Toda a memória e conhecimento serão salvos em ./my_project_storage/ +crew = Crew( + agents=[...], + tasks=[...], + memory=True +) +``` + +#### Opção 2: Caminho de Armazenamento Personalizado +```python +import os +from crewai import Crew +from crewai.memory import LongTermMemory +from crewai.memory.storage.ltm_sqlite_storage import LTMSQLiteStorage + +# Configurar local de armazenamento personalizado +custom_storage_path = "./storage" +os.makedirs(custom_storage_path, exist_ok=True) + +crew = Crew( + memory=True, + long_term_memory=LongTermMemory( + storage=LTMSQLiteStorage( + db_path=f"{custom_storage_path}/memory.db" + ) + ) +) +``` + +#### Opção 3: Armazenamento Específico de Projeto +```python +import os +from pathlib import Path + +# Armazenar no diretório do projeto +project_root = Path(__file__).parent +storage_dir = project_root / "crewai_storage" + +os.environ["CREWAI_STORAGE_DIR"] = str(storage_dir) + +# Todo o armazenamento ficará agora na pasta do projeto +``` + +### Padrão do Provedor de Embedding + + +**Provedor de Embedding Padrão**: O CrewAI utiliza embeddings do OpenAI por padrão para garantir consistência e confiabilidade. Você pode facilmente customizar para combinar com seu provedor LLM ou utilizar embeddings locais. + + +#### Compreendendo o Comportamento Padrão +```python +# Ao utilizar Claude como seu LLM... +from crewai import Agent, LLM + +agent = Agent( + role="Analyst", + goal="Analyze data", + backstory="Expert analyst", + llm=LLM(provider="anthropic", model="claude-3-sonnet") # Usando Claude +) + +# O CrewAI usará embeddings OpenAI por padrão para garantir consistência +# Você pode customizar facilmente para combinar com seu provedor preferido +``` + +#### Personalizando Provedores de Embedding +```python +from crewai import Crew + +# Opção 1: Combinar com seu provedor de LLM +crew = Crew( + agents=[agent], + tasks=[task], + memory=True, + embedder={ + "provider": "anthropic", # Combine com seu provedor de LLM + "config": { + "api_key": "your-anthropic-key", + "model": "text-embedding-3-small" + } + } +) + +# Opção 2: Use embeddings locais (sem chamadas para API externa) +crew = Crew( + agents=[agent], + tasks=[task], + memory=True, + embedder={ + "provider": "ollama", + "config": {"model": "mxbai-embed-large"} + } +) +``` + +### Depuração de Problemas de Armazenamento + +#### Verifique Permissões do Armazenamento +```python +import os +from crewai.utilities.paths import db_storage_path + +storage_path = db_storage_path() +print(f"Storage path: {storage_path}") +print(f"Path exists: {os.path.exists(storage_path)}") +print(f"Is writable: {os.access(storage_path, os.W_OK) if os.path.exists(storage_path) else 'Path does not exist'}") + +# Crie com permissões apropriadas +if not os.path.exists(storage_path): + os.makedirs(storage_path, mode=0o755, exist_ok=True) + print(f"Created storage directory: {storage_path}") +``` + +#### Inspecione Coleções do ChromaDB +```python +import chromadb +from crewai.utilities.paths import db_storage_path + +# Conecte-se ao ChromaDB do CrewAI +storage_path = db_storage_path() +chroma_path = os.path.join(storage_path, "knowledge") + +if os.path.exists(chroma_path): + client = chromadb.PersistentClient(path=chroma_path) + collections = client.list_collections() + + print("ChromaDB Collections:") + for collection in collections: + print(f" - {collection.name}: {collection.count()} documentos") +else: + print("No ChromaDB storage found") +``` + +#### Resetar Armazenamento (Depuração) +```python +from crewai import Crew + +# Limpar todo o armazenamento de memória +crew = Crew(agents=[...], tasks=[...], memory=True) + +# Limpar tipos específicos de memória +crew.reset_memories(command_type='short') # Memória de curto prazo +crew.reset_memories(command_type='long') # Memória de longo prazo +crew.reset_memories(command_type='entity') # Memória de entidades +crew.reset_memories(command_type='knowledge') # Armazenamento de conhecimento +``` + +### Melhores Práticas para Produção + +1. **Defina o `CREWAI_STORAGE_DIR`** para um local conhecido em produção para maior controle +2. **Escolha explicitamente provedores de embeddings** para coincidir com seu setup de LLM +3. **Monitore o tamanho do diretório de armazenamento** em casos de grande escala +4. **Inclua diretórios de armazenamento** em sua política de backup +5. **Defina permissões apropriadas de arquivo** (0o755 para diretórios, 0o644 para arquivos) +6. **Use caminhos relativos ao projeto** para implantações containerizadas + +### Problemas Comuns de Armazenamento + +**Erros "ChromaDB permission denied":** +```bash +# Corrija permissões +chmod -R 755 ~/.local/share/CrewAI/ +``` + +**Erros "Database is locked":** +```python +# Certifique-se que apenas uma instância CrewAI acesse o armazenamento +import fcntl +import os + +storage_path = db_storage_path() +lock_file = os.path.join(storage_path, ".crewai.lock") + +with open(lock_file, 'w') as f: + fcntl.flock(f.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB) + # Seu código CrewAI aqui +``` + +**Armazenamento não persiste entre execuções:** +```python +# Verifique se o local do armazenamento é consistente +import os +print("CREWAI_STORAGE_DIR:", os.getenv("CREWAI_STORAGE_DIR")) +print("Current working directory:", os.getcwd()) +print("Computed storage path:", db_storage_path()) +``` + +## Configuração Personalizada de Embedders + +O CrewAI suporta múltiplos provedores de embeddings para oferecer flexibilidade na escolha da melhor opção para seu caso de uso. Aqui está um guia completo para configuração de diferentes provedores de embeddings para seu sistema de memória. + +### Por que Escolher Diferentes Provedores de Embeddings? + +- **Otimização de Custos**: Embeddings locais (Ollama) são gratuitos após configuração inicial +- **Privacidade**: Mantenha seus dados locais com Ollama ou use seu provedor preferido na nuvem +- **Desempenho**: Alguns modelos têm melhor desempenho para domínios ou idiomas específicos +- **Consistência**: Combine seu provedor de embedding com o de LLM +- **Conformidade**: Atenda a requisitos regulatórios ou organizacionais + +### OpenAI Embeddings (Padrão) + +A OpenAI oferece embeddings confiáveis e de alta qualidade para a maioria dos cenários. + +```python +from crewai import Crew + +# Configuração básica OpenAI (usa a variável de ambiente OPENAI_API_KEY) +crew = Crew( + agents=[...], + tasks=[...], + memory=True, + embedder={ + "provider": "openai", + "config": { + "model": "text-embedding-3-small" # ou "text-embedding-3-large" + } + } +) + +# Configuração avançada OpenAI +crew = Crew( + memory=True, + embedder={ + "provider": "openai", + "config": { + "api_key": "your-openai-api-key", # Opcional: sobrescreve variável de ambiente + "model": "text-embedding-3-large", + "dimensions": 1536, # Opcional: reduz as dimensões para armazenamento menor + "organization_id": "your-org-id" # Opcional: para contas organizacionais + } + } +) +``` + +### Azure OpenAI Embeddings + +Para empresas que utilizam deploys Azure OpenAI. + +```python +crew = Crew( + memory=True, + embedder={ + "provider": "openai", # Use openai como provider para Azure + "config": { + "api_key": "your-azure-api-key", + "api_base": "https://your-resource.openai.azure.com/", + "api_type": "azure", + "api_version": "2023-05-15", + "model": "text-embedding-3-small", + "deployment_id": "your-deployment-name" # Nome do deploy Azure + } + } +) +``` + +### Google AI Embeddings + +Use modelos de embeddings de texto do Google para integração com serviços do Google Cloud. + +```python +crew = Crew( + memory=True, + embedder={ + "provider": "google", + "config": { + "api_key": "your-google-api-key", + "model": "text-embedding-004" # ou "text-embedding-preview-0409" + } + } +) +``` + +### Vertex AI Embeddings + +Para usuários do Google Cloud com acesso ao Vertex AI. + +```python +crew = Crew( + memory=True, + embedder={ + "provider": "vertexai", + "config": { + "project_id": "your-gcp-project-id", + "region": "us-central1", # ou sua região preferencial + "api_key": "your-service-account-key", + "model_name": "textembedding-gecko" + } + } +) +``` + +### Ollama Embeddings (Local) + +Execute embeddings localmente para privacidade e economia. + +```python +# Primeiro, instale e rode Ollama localmente, depois baixe um modelo de embedding: +# ollama pull mxbai-embed-large + +crew = Crew( + memory=True, + embedder={ + "provider": "ollama", + "config": { + "model": "mxbai-embed-large", # ou "nomic-embed-text" + "url": "http://localhost:11434/api/embeddings" # URL padrão do Ollama + } + } +) + +# Para instalações personalizadas do Ollama +crew = Crew( + memory=True, + embedder={ + "provider": "ollama", + "config": { + "model": "mxbai-embed-large", + "url": "http://your-ollama-server:11434/api/embeddings" + } + } +) +``` + +### Cohere Embeddings + +Utilize os modelos de embedding da Cohere para suporte multilíngue. + +```python +crew = Crew( + memory=True, + embedder={ + "provider": "cohere", + "config": { + "api_key": "your-cohere-api-key", + "model": "embed-english-v3.0" # ou "embed-multilingual-v3.0" + } + } +) +``` + +### VoyageAI Embeddings + +Embeddings de alto desempenho otimizados para tarefas de recuperação. + +```python +crew = Crew( + memory=True, + embedder={ + "provider": "voyageai", + "config": { + "api_key": "your-voyage-api-key", + "model": "voyage-large-2", # ou "voyage-code-2" para código + "input_type": "document" # ou "query" + } + } +) +``` + +### AWS Bedrock Embeddings + +Para usuários AWS com acesso ao Bedrock. + +```python +crew = Crew( + memory=True, + embedder={ + "provider": "bedrock", + "config": { + "aws_access_key_id": "your-access-key", + "aws_secret_access_key": "your-secret-key", + "region_name": "us-east-1", + "model": "amazon.titan-embed-text-v1" + } + } +) +``` + +### Hugging Face Embeddings + +Utilize modelos open-source do Hugging Face. + +```python +crew = Crew( + memory=True, + embedder={ + "provider": "huggingface", + "config": { + "api_key": "your-hf-token", # Opcional para modelos públicos + "model": "sentence-transformers/all-MiniLM-L6-v2", + "api_url": "https://api-inference.huggingface.co" # ou seu endpoint customizado + } + } +) +``` + +### IBM Watson Embeddings + +Para usuários do IBM Cloud. + +```python +crew = Crew( + memory=True, + embedder={ + "provider": "watson", + "config": { + "api_key": "your-watson-api-key", + "url": "your-watson-instance-url", + "model": "ibm/slate-125m-english-rtrvr" + } + } +) +``` + +### Como Escolher o Provedor de Embedding Certo + +| Provedor | Melhor Para | Prós | Contras | +|:---------|:----------|:------|:------| +| **OpenAI** | Uso geral, confiabilidade | Alta qualidade, bem testado | Custo, requer chave de API | +| **Ollama** | Privacidade, economia | Gratuito, local, privado | Requer configuração local | +| **Google AI** | Ecossistema Google | Bom desempenho | Requer conta Google | +| **Azure OpenAI** | Empresas, conformidade | Recursos corporativos | Configuração mais complexa | +| **Cohere** | Conteúdo multilíngue | Excelente suporte a idiomas | Uso especializado | +| **VoyageAI** | Tarefas de busca e recuperação | Otimizado para pesquisa | Provedor mais novo | + +### Configuração via Variável de Ambiente + +Para segurança, armazene chaves de API em variáveis de ambiente: + +```python +import os + +# Configurar variáveis de ambiente +os.environ["OPENAI_API_KEY"] = "your-openai-key" +os.environ["GOOGLE_API_KEY"] = "your-google-key" +os.environ["COHERE_API_KEY"] = "your-cohere-key" + +# Use sem expor as chaves no código +crew = Crew( + memory=True, + embedder={ + "provider": "openai", + "config": { + "model": "text-embedding-3-small" + # A chave de API será carregada automaticamente da variável de ambiente + } + } +) +``` + +### Testando Diferentes Provedores de Embedding + +Compare provedores de embedding para o seu caso de uso específico: + +```python +from crewai import Crew +from crewai.utilities.paths import db_storage_path + +# Testar diferentes provedores com os mesmos dados +providers_to_test = [ + { + "name": "OpenAI", + "config": { + "provider": "openai", + "config": {"model": "text-embedding-3-small"} + } + }, + { + "name": "Ollama", + "config": { + "provider": "ollama", + "config": {"model": "mxbai-embed-large"} + } + } +] + +for provider in providers_to_test: + print(f"\nTesting {provider['name']} embeddings...") + + # Criar crew com embedder específico + crew = Crew( + agents=[...], + tasks=[...], + memory=True, + embedder=provider['config'] + ) + + # Execute o teste e meça o desempenho + result = crew.kickoff() + print(f"{provider['name']} completed successfully") +``` + +### Solução de Problemas de Embeddings + +**Erros de modelo não encontrado:** +```python +# Verifique disponibilidade do modelo +from crewai.utilities.embedding_configurator import EmbeddingConfigurator + +configurator = EmbeddingConfigurator() +try: + embedder = configurator.configure_embedder({ + "provider": "ollama", + "config": {"model": "mxbai-embed-large"} + }) + print("Embedder configured successfully") +except Exception as e: + print(f"Configuration error: {e}") +``` + +**Problemas com chave de API:** +```python +import os + +# Verifique se as chaves de API estão configuradas +required_keys = ["OPENAI_API_KEY", "GOOGLE_API_KEY", "COHERE_API_KEY"] +for key in required_keys: + if os.getenv(key): + print(f"✅ {key} is set") + else: + print(f"❌ {key} is not set") +``` + +**Comparação de desempenho:** +```python +import time + +def test_embedding_performance(embedder_config, test_text="This is a test document"): + start_time = time.time() + + crew = Crew( + agents=[...], + tasks=[...], + memory=True, + embedder=embedder_config + ) + + # Simula operação de memória + crew.kickoff() + + end_time = time.time() + return end_time - start_time + +# Comparar desempenho +openai_time = test_embedding_performance({ + "provider": "openai", + "config": {"model": "text-embedding-3-small"} +}) + +ollama_time = test_embedding_performance({ + "provider": "ollama", + "config": {"model": "mxbai-embed-large"} +}) + +print(f"OpenAI: {openai_time:.2f}s") +print(f"Ollama: {ollama_time:.2f}s") +``` + +## 2. Memória de Usuário com Mem0 (Legado) + + +**Abordagem Legada**: Embora totalmente funcional, esta abordagem é considerada legada. Para novos projetos que exijam memória específica do usuário, considere usar Memória Externa. + + +A Memória de Usuário se integra com o [Mem0](https://mem0.ai/) para fornecer memória específica do usuário que persiste entre sessões e se integra ao sistema de memória contextual da crew. + +### Pré-requisitos +```bash +pip install mem0ai +``` + +### Configuração Mem0 na Nuvem +```python +import os +from crewai import Crew, Process + +# Defina sua chave de API do Mem0 +os.environ["MEM0_API_KEY"] = "m0-your-api-key" + +crew = Crew( + agents=[...], + tasks=[...], + memory=True, # Necessário para integração com a memória contextual + memory_config={ + "provider": "mem0", + "config": {"user_id": "john"}, + "user_memory": {} # Obrigatório - inicializa a memória de usuário + }, + process=Process.sequential, + verbose=True +) +``` + +### Configuração Avançada Mem0 +```python +crew = Crew( + agents=[...], + tasks=[...], + memory=True, + memory_config={ + "provider": "mem0", + "config": { + "user_id": "john", + "org_id": "my_org_id", # Opcional + "project_id": "my_project_id", # Opcional + "api_key": "custom-api-key" # Opcional - sobrescreve variável de ambiente + }, + "user_memory": {} + } +) +``` + +### Configuração Mem0 Local +```python +crew = Crew( + agents=[...], + tasks=[...], + memory=True, + memory_config={ + "provider": "mem0", + "config": { + "user_id": "john", + "local_mem0_config": { + "vector_store": { + "provider": "qdrant", + "config": {"host": "localhost", "port": 6333} + }, + "llm": { + "provider": "openai", + "config": {"api_key": "your-api-key", "model": "gpt-4"} + }, + "embedder": { + "provider": "openai", + "config": {"api_key": "your-api-key", "model": "text-embedding-3-small"} + } + } + }, + "user_memory": {} + } +) +``` + +## 3. Memória Externa (Nova Abordagem) + +A Memória Externa fornece um sistema de memória autônomo que opera independentemente da memória interna da crew. Isso é ideal para provedores de memória especializados ou compartilhamento de memória entre aplicações. + +### Memória Externa Básica com Mem0 +```python +import os +from crewai import Agent, Crew, Process, Task +from crewai.memory.external.external_memory import ExternalMemory + +os.environ["MEM0_API_KEY"] = "your-api-key" + +# Criar instância de memória externa +external_memory = ExternalMemory( + embedder_config={ + "provider": "mem0", + "config": {"user_id": "U-123"} + } +) + +crew = Crew( + agents=[...], + tasks=[...], + external_memory=external_memory, # Independente da memória básica + process=Process.sequential, + verbose=True +) +``` + +### Implementação Personalizada de Armazenamento +```python +from crewai.memory.external.external_memory import ExternalMemory +from crewai.memory.storage.interface import Storage + +class CustomStorage(Storage): + def __init__(self): + self.memories = [] + + def save(self, value, metadata=None, agent=None): + self.memories.append({ + "value": value, + "metadata": metadata, + "agent": agent + }) + + def search(self, query, limit=10, score_threshold=0.5): + # Implemente sua lógica de busca aqui + return [m for m in self.memories if query.lower() in str(m["value"]).lower()] + + def reset(self): + self.memories = [] + +# Usando armazenamento customizado +external_memory = ExternalMemory(storage=CustomStorage()) + +crew = Crew( + agents=[...], + tasks=[...], + external_memory=external_memory +) +``` + +## Comparação dos Sistemas de Memória + +| Recurso | Memória Básica | Memória de Usuário (Legado) | Memória Externa | +|---------|---------------|-----------------------------|----------------| +| **Complexidade de Setup** | Simples | Média | Média | +| **Integração** | Contextual integrada | Contextual + específica do usuário | Autônoma | +| **Armazenamento** | Arquivos locais | Mem0 Cloud/Local | Customizada/Mem0 | +| **Multi-sessão** | ✅ | ✅ | ✅ | +| **Especificidade do Usuário** | ❌ | ✅ | ✅ | +| **Provedores Customizados** | Limitado | Apenas Mem0 | Qualquer provedor | +| **Recomendado para** | Maioria dos casos | Projetos legados | Necessidades especializadas | + +## Provedores de Embedding Suportados + +### OpenAI (Padrão) +```python +crew = Crew( + memory=True, + embedder={ + "provider": "openai", + "config": {"model": "text-embedding-3-small"} + } +) +``` + +### Ollama +```python +crew = Crew( + memory=True, + embedder={ + "provider": "ollama", + "config": {"model": "mxbai-embed-large"} + } +) +``` + +### Google AI +```python +crew = Crew( + memory=True, + embedder={ + "provider": "google", + "config": { + "api_key": "your-api-key", + "model": "text-embedding-004" + } + } +) +``` + +### Azure OpenAI +```python +crew = Crew( + memory=True, + embedder={ + "provider": "openai", + "config": { + "api_key": "your-api-key", + "api_base": "https://your-resource.openai.azure.com/", + "api_version": "2023-05-15", + "model_name": "text-embedding-3-small" + } + } +) +``` + +### Vertex AI +```python +crew = Crew( + memory=True, + embedder={ + "provider": "vertexai", + "config": { + "project_id": "your-project-id", + "region": "your-region", + "api_key": "your-api-key", + "model_name": "textembedding-gecko" + } + } +) +``` + +## Melhores Práticas de Segurança + +### Variáveis de Ambiente +```python +import os +from crewai import Crew + +# Armazene dados sensíveis em variáveis de ambiente +crew = Crew( + memory=True, + embedder={ + "provider": "openai", + "config": { + "api_key": os.getenv("OPENAI_API_KEY"), + "model": "text-embedding-3-small" + } + } +) +``` + +### Segurança no Armazenamento +```python +import os +from crewai import Crew +from crewai.memory import LongTermMemory +from crewai.memory.storage.ltm_sqlite_storage import LTMSQLiteStorage + +# Use caminhos seguros para armazenamento +storage_path = os.getenv("CREWAI_STORAGE_DIR", "./storage") +os.makedirs(storage_path, mode=0o700, exist_ok=True) # Permissões restritas + +crew = Crew( + memory=True, + long_term_memory=LongTermMemory( + storage=LTMSQLiteStorage( + db_path=f"{storage_path}/memory.db" + ) + ) +) +``` + +## Solução de Problemas + +### Problemas Comuns + +**A memória não está persistindo entre sessões?** +- Verifique a variável de ambiente `CREWAI_STORAGE_DIR` +- Garanta permissões de escrita no diretório de armazenamento +- Certifique-se que a memória está ativada com `memory=True` + +**Erros de autenticação no Mem0?** +- Verifique se a variável de ambiente `MEM0_API_KEY` está definida +- Confira permissões da chave de API no painel do Mem0 +- Certifique-se de que o pacote `mem0ai` está instalado + +**Alto uso de memória com grandes volumes de dados?** +- Considere usar Memória Externa com armazenamento personalizado +- Implemente paginação nos métodos de busca do armazenamento customizado +- Utilize modelos de embedding menores para menor consumo de memória + +### Dicas de Desempenho + +- Use `memory=True` para a maioria dos casos (mais simples e rápido) +- Só utilize Memória de Usuário se precisar de persistência específica por usuário +- Considere Memória Externa para necessidades de grande escala ou especializadas +- Prefira modelos de embedding menores para maior rapidez +- Defina limites apropriados de busca para controlar o tamanho da recuperação + +## Benefícios do Sistema de Memória do CrewAI + +- 🦾 **Aprendizado Adaptativo:** As crews tornam-se mais eficientes ao longo do tempo, adaptando-se a novas informações e refinando sua abordagem para tarefas. +- 🫡 **Personalização Avançada:** A memória permite que agentes lembrem preferências do usuário e interações passadas, proporcionando experiências personalizadas. +- 🧠 **Melhoria na Resolução de Problemas:** O acesso a um rico acervo de memória auxilia os agentes a tomar decisões mais informadas, recorrendo a aprendizados prévios e contextuais. + +## Conclusão + +Integrar o sistema de memória do CrewAI em seus projetos é simples. Ao aproveitar os componentes e configurações oferecidos, +você rapidamente capacita seus agentes a lembrar, raciocinar e aprender com suas interações, desbloqueando novos níveis de inteligência e capacidade. \ No newline at end of file diff --git a/docs/pt-BR/concepts/planning.mdx b/docs/pt-BR/concepts/planning.mdx new file mode 100644 index 000000000..2f16c9779 --- /dev/null +++ b/docs/pt-BR/concepts/planning.mdx @@ -0,0 +1,152 @@ +--- +title: Planejamento +description: Aprenda como adicionar planejamento à sua CrewAI Crew e melhorar sua performance. +icon: ruler-combined +--- + +## Visão geral + +O recurso de planejamento no CrewAI permite que você adicione capacidade de planejamento à sua crew. Quando ativado, antes de cada iteração da Crew, todas as informações da Crew são enviadas para um AgentPlanner que irá planejar as tarefas passo a passo, e este plano será adicionado à descrição de cada tarefa. + +### Usando o recurso de Planejamento + +Começar a usar o recurso de planejamento é muito simples, o único passo necessário é adicionar `planning=True` à sua Crew: + + +```python Code +from crewai import Crew, Agent, Task, Process + +# Monte sua crew com capacidades de planejamento +my_crew = Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + planning=True, +) +``` + + +A partir deste ponto, sua crew terá o planejamento ativado, e as tarefas serão planejadas antes de cada iteração. + + +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. + + +#### 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. + + +```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 '```'. +``` + \ No newline at end of file diff --git a/docs/pt-BR/concepts/processes.mdx b/docs/pt-BR/concepts/processes.mdx new file mode 100644 index 000000000..8864616f6 --- /dev/null +++ b/docs/pt-BR/concepts/processes.mdx @@ -0,0 +1,66 @@ +--- +title: Processos +description: Guia detalhado sobre o gerenciamento de fluxos de trabalho através de processos no CrewAI, com detalhes de implementação atualizados. +icon: bars-staggered +--- + +## Visão Geral + + + 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. + + +## Implementações de Processos + +- **Sequencial**: Executa tarefas de forma sequencial, garantindo que as tarefas sejam concluídas em uma progressão ordenada. +- **Hierárquico**: Organiza tarefas em uma hierarquia gerencial, onde as tarefas são delegadas e executadas com base numa cadeia de comando estruturada. Um modelo de linguagem de gerente (`manager_llm`) ou um agente gerente personalizado (`manager_agent`) deve ser especificado na crew para habilitar o processo hierárquico, facilitando a criação e o gerenciamento de tarefas pelo gerente. +- **Processo Consensual (Planejado)**: Visando a tomada de decisão colaborativa entre agentes para execução de tarefas, esse tipo de processo introduz uma abordagem democrática ao gerenciamento de tarefas dentro do CrewAI. Está planejado para desenvolvimento futuro e ainda não está implementado no código-fonte. + +## O Papel dos Processos no Trabalho em Equipe +Os processos permitem que agentes individuais atuem como uma unidade coesa, otimizando seus esforços para atingir objetivos comuns com eficiência e coerência. + +## Atribuindo Processos a uma Crew +Para atribuir um processo a uma crew, especifique o tipo de processo ao criar a crew para definir a estratégia de execução. Para um processo hierárquico, garanta a definição de `manager_llm` ou `manager_agent` para o agente gerente. + +```python +from crewai import Crew, Process + +# Exemplo: Criando uma crew com processo sequencial +crew = Crew( + agents=my_agents, + tasks=my_tasks, + process=Process.sequential +) + +# Exemplo: Criando uma crew com processo hierárquico +# Certifique-se de fornecer um manager_llm ou manager_agent +crew = Crew( + agents=my_agents, + tasks=my_tasks, + process=Process.hierarchical, + manager_llm="gpt-4o" + # ou + # manager_agent=my_manager_agent +) +``` +**Nota:** Certifique-se de que `my_agents` e `my_tasks` estejam definidos antes de criar o objeto `Crew`, e para o processo hierárquico, é necessário também fornecer o `manager_llm` ou `manager_agent`. + +## Processo Sequencial + +Este método reflete fluxos de trabalho dinâmicos de equipes, progredindo nas tarefas de maneira cuidadosa e sistemática. A execução das tarefas segue a ordem preestabelecida na lista de tarefas, com a saída de uma tarefa servindo de contexto para a próxima. + +Para personalizar o contexto das tarefas, utilize o parâmetro `context` na classe `Task` para especificar as saídas que devem ser usadas como contexto para as tarefas subsequentes. + +## Processo Hierárquico + +Emulando uma hierarquia corporativa, o CrewAI permite especificar um agente gerente personalizado ou criar um automaticamente, exigindo a especificação de um modelo de linguagem de gerente (`manager_llm`). Esse agente supervisiona a execução das tarefas, incluindo planejamento, delegação e validação. As tarefas não são pré-atribuídas; o gerente aloca tarefas aos agentes com base em suas capacidades, revisa as saídas e avalia a conclusão das tarefas. + +## Classe Process: Visão Detalhada + +A classe `Process` é implementada como uma enumeração (`Enum`), garantindo segurança de tipo e restringindo os valores de processos aos tipos definidos (`sequential`, `hierarchical`). O processo consensual está planejado para inclusão futura, reforçando nosso compromisso com o desenvolvimento contínuo e a inovação. + +## Conclusão + +A colaboração estruturada possibilitada pelos processos dentro do CrewAI é fundamental para permitir o trabalho em equipe sistemático entre agentes. +Esta documentação foi atualizada para refletir os mais recentes recursos, melhorias e a planejada integração do Processo Consensual, garantindo que os usuários tenham acesso às informações mais atuais e abrangentes. \ No newline at end of file diff --git a/docs/pt-BR/concepts/reasoning.mdx b/docs/pt-BR/concepts/reasoning.mdx new file mode 100644 index 000000000..205edb48c --- /dev/null +++ b/docs/pt-BR/concepts/reasoning.mdx @@ -0,0 +1,147 @@ +--- +title: Reasoning +description: "Aprenda como habilitar e usar o reasoning do agente para aprimorar a execução de tarefas." +icon: brain +--- + +## Visão Geral + +O reasoning do agente é um recurso que permite que agentes reflitam sobre uma tarefa e criem um plano antes da execução. Isso ajuda os agentes a abordarem tarefas de forma mais metódica e garante que estejam preparados para realizar o trabalho atribuído. + +## Uso + +Para habilitar o reasoning para um agente, basta definir `reasoning=True` ao criar o agente: + +```python +from crewai import Agent + +agent = Agent( + role="Data Analyst", + goal="Analyze complex datasets and provide insights", + backstory="You are an experienced data analyst with expertise in finding patterns in complex data.", + reasoning=True, # Enable reasoning + max_reasoning_attempts=3 # Optional: Set a maximum number of reasoning attempts +) +``` + +## Como Funciona + +Quando o reasoning está habilitado, antes de executar uma tarefa, o agente irá: + +1. Refletir sobre a tarefa e criar um plano detalhado +2. Avaliar se está pronto para executar a tarefa +3. Refinar o plano conforme necessário até estar pronto ou até o limite de max_reasoning_attempts ser atingido +4. Inserir o plano de reasoning na descrição da tarefa antes da execução + +Esse processo ajuda o agente a dividir tarefas complexas em etapas gerenciáveis e identificar potenciais desafios antes de começar. + +## Opções de Configuração + + + Ativa ou desativa o reasoning + + + + 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. + + +## Exemplo + +Aqui está um exemplo completo: + +```python +from crewai import Agent, Task, Crew + +# Create an agent with reasoning enabled +analyst = Agent( + role="Data Analyst", + goal="Analyze data and provide insights", + backstory="You are an expert data analyst.", + reasoning=True, + max_reasoning_attempts=3 # Optional: Set a limit on reasoning attempts +) + +# Create a task +analysis_task = Task( + description="Analyze the provided sales data and identify key trends.", + expected_output="A report highlighting the top 3 sales trends.", + agent=analyst +) + +# Create a crew and run the task +crew = Crew(agents=[analyst], tasks=[analysis_task]) +result = crew.kickoff() + +print(result) +``` + +## Tratamento de Erros + +O processo de reasoning foi projetado para ser robusto, com tratamento de erros integrado. Se ocorrer um erro durante o reasoning, o agente prosseguirá com a execução da tarefa sem o plano de reasoning. Isso garante que as tarefas ainda possam ser executadas mesmo que o processo de reasoning falhe. + +Veja como lidar com possíveis erros no seu código: + +```python +from crewai import Agent, Task +import logging + +# Set up logging to capture any reasoning errors +logging.basicConfig(level=logging.INFO) + +# Create an agent with reasoning enabled +agent = Agent( + role="Data Analyst", + goal="Analyze data and provide insights", + reasoning=True, + max_reasoning_attempts=3 +) + +# Create a task +task = Task( + description="Analyze the provided sales data and identify key trends.", + expected_output="A report highlighting the top 3 sales trends.", + agent=agent +) + +# Execute the task +# If an error occurs during reasoning, it will be logged and execution will continue +result = agent.execute_task(task) +``` + +## Exemplo de Saída de reasoning + +Veja um exemplo de como pode ser um plano de reasoning para uma tarefa de análise de dados: + +``` +Task: Analyze the provided sales data and identify key trends. + +Reasoning Plan: +I'll analyze the sales data to identify the top 3 trends. + +1. Understanding of the task: + I need to analyze sales data to identify key trends that would be valuable for business decision-making. + +2. Key steps I'll take: + - First, I'll examine the data structure to understand what fields are available + - Then I'll perform exploratory data analysis to identify patterns + - Next, I'll analyze sales by time periods to identify temporal trends + - I'll also analyze sales by product categories and customer segments + - Finally, I'll identify the top 3 most significant trends + +3. Approach to challenges: + - If the data has missing values, I'll decide whether to fill or filter them + - If the data has outliers, I'll investigate whether they're valid data points or errors + - If trends aren't immediately obvious, I'll apply statistical methods to uncover patterns + +4. Use of available tools: + - I'll use data analysis tools to explore and visualize the data + - I'll use statistical tools to identify significant patterns + - I'll use knowledge retrieval to access relevant information about sales analysis + +5. Expected outcome: + A concise report highlighting the top 3 sales trends with supporting evidence from the data. + +READY: I am ready to execute the task. +``` + +Esse plano de reasoning ajuda o agente a organizar sua abordagem para a tarefa, considerar possíveis desafios e garantir que entregará o resultado esperado. diff --git a/docs/pt-BR/concepts/tasks.mdx b/docs/pt-BR/concepts/tasks.mdx new file mode 100644 index 000000000..38604439e --- /dev/null +++ b/docs/pt-BR/concepts/tasks.mdx @@ -0,0 +1,996 @@ +--- +title: Tarefas +description: Guia detalhado sobre como gerenciar e criar tarefas dentro do framework CrewAI. +icon: list-check +--- + +## Visão Geral + +No framework CrewAI, uma `Task` (Tarefa) é uma atribuição específica executada por um `Agent` (Agente). + +As tarefas fornecem todos os detalhes necessários para sua execução, como descrição, agente responsável, ferramentas exigidas e mais, facilitando uma ampla gama de complexidades de ação. + +As tarefas dentro do CrewAI podem ser colaborativas, exigindo que múltiplos agentes trabalhem juntos. Isso é gerenciado por meio das propriedades da tarefa e orquestrado pelo processo do Crew, potencializando o trabalho em equipe e a eficiência. + + +O CrewAI Enterprise inclui um Construtor Visual de Tarefas no Crew Studio, que simplifica a criação e o encadeamento de tarefas complexas. Projete seus fluxos de tarefas visualmente e teste-os em tempo real sem necessidade de escrever código. + +![Task Builder Screenshot](/images/enterprise/crew-studio-interface.png) + +O Construtor Visual de Tarefas permite: +- Criação de tarefas via arrastar-e-soltar +- Visualização de dependências e fluxo de tarefas +- Testes e validações em tempo real +- Fácil compartilhamento e colaboração + + +### Fluxo de Execução de Tarefas + +As tarefas podem ser executadas de duas maneiras: +- **Sequencial**: As tarefas são executadas na ordem em que são definidas +- **Hierárquica**: As tarefas são atribuídas aos agentes com base em seus papéis e especialidades + +O fluxo de execução é definido ao criar o crew: +```python Code +crew = Crew( + agents=[agent1, agent2], + tasks=[task1, task2], + process=Process.sequential # ou Process.hierarchical +) +``` + +## Atributos da Tarefa + +| Atributo | Parâmetros | Tipo | Descrição | +| :------------------------------- | :---------------- | :--------------------------- | :----------------------------------------------------------------------------------------------------------------- | +| **Descrição** | `description` | `str` | Uma declaração clara e concisa do que a tarefa envolve. | +| **Saída Esperada** | `expected_output` | `str` | Uma descrição detalhada de como deve ser o resultado da tarefa concluída. | +| **Nome** _(opcional)_ | `name` | `Optional[str]` | Um identificador de nome para a tarefa. | +| **Agente** _(opcional)_ | `agent` | `Optional[BaseAgent]` | O agente responsável por executar a tarefa. | +| **Ferramentas** _(opcional)_ | `tools` | `List[BaseTool]` | As ferramentas/recursos que o agente pode usar para esta tarefa. | +| **Contexto** _(opcional)_ | `context` | `Optional[List["Task"]]` | Outras tarefas cujas saídas serão usadas como contexto para esta tarefa. | +| **Execução Assíncrona** _(opc.)_ | `async_execution` | `Optional[bool]` | Se a tarefa deve ser executada de forma assíncrona. O padrão é False. | +| **Input Humano** _(opcional)_ | `human_input` | `Optional[bool]` | Se a tarefa deve ter uma revisão humana da resposta final do agente. O padrão é False. | +| **Markdown** _(opcional)_ | `markdown` | `Optional[bool]` | Se a tarefa deve instruir o agente a retornar a resposta final formatada em Markdown. O padrão é False. | +| **Config** _(opcional)_ | `config` | `Optional[Dict[str, Any]]` | Parâmetros de configuração específicos da tarefa. | +| **Arquivo de Saída** _(opcional)_| `output_file` | `Optional[str]` | Caminho do arquivo para armazenar a saída da tarefa. | +| **Saída JSON** _(opcional)_ | `output_json` | `Optional[Type[BaseModel]]` | Um modelo Pydantic para estruturar a saída em JSON. | +| **Output Pydantic** _(opcional)_ | `output_pydantic` | `Optional[Type[BaseModel]]` | Um modelo Pydantic para a saída da tarefa. | +| **Callback** _(opcional)_ | `callback` | `Optional[Any]` | Função/objeto a ser executado após a conclusão da tarefa. | + +## Criando Tarefas + +Existem duas maneiras de criar tarefas no CrewAI: utilizando **configuração YAML (recomendado)** ou definindo-as **diretamente no código**. + +### Configuração YAML (Recomendado) + +Utilizar configuração YAML oferece uma forma mais limpa e de fácil manutenção para definir tarefas. Recomendamos fortemente esse método em seus projetos CrewAI. + +Após criar seu projeto CrewAI conforme indicado na seção [Instalação](/pt-BR/installation), navegue até o arquivo `src/latest_ai_development/config/tasks.yaml` e modifique o template para refletir os requisitos específicos das tarefas. + + +Variáveis em seus arquivos YAML (como `{topic}`) serão substituídas por valores vindos dos seus inputs ao executar o crew: +```python Code +crew.kickoff(inputs={'topic': 'AI Agents'}) +``` + + +Veja um exemplo de configuração de tarefas usando YAML: + +```yaml tasks.yaml +research_task: + description: > + Realize uma pesquisa detalhada sobre {topic} + Certifique-se de encontrar informações interessantes e relevantes considerando + que o ano atual é 2025. + expected_output: > + Uma lista com 10 tópicos em bullet points das informações mais relevantes sobre {topic} + agent: researcher + +reporting_task: + description: > + Revise o contexto recebido e expanda cada tópico em uma seção completa de um relatório. + Certifique-se de que o relatório seja detalhado e contenha todas as informações relevantes. + expected_output: > + Um relatório completo com os principais tópicos, cada um com uma seção cheia de informações. + Formatado em markdown sem '```' + agent: reporting_analyst + markdown: true + output_file: report.md +``` + +Para usar essa configuração YAML em seu código, crie uma classe crew que herda de `CrewBase`: + +```python crew.py +# src/latest_ai_development/crew.py + +from crewai import Agent, Crew, Process, Task +from crewai.project import CrewBase, agent, crew, task +from crewai_tools import SerperDevTool + +@CrewBase +class LatestAiDevelopmentCrew(): + """LatestAiDevelopment crew""" + + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], # type: ignore[index] + verbose=True, + tools=[SerperDevTool()] + ) + + @agent + def reporting_analyst(self) -> Agent: + return Agent( + config=self.agents_config['reporting_analyst'], # type: ignore[index] + verbose=True + ) + + @task + def research_task(self) -> Task: + return Task( + config=self.tasks_config['research_task'] # type: ignore[index] + ) + + @task + def reporting_task(self) -> Task: + return Task( + config=self.tasks_config['reporting_task'] # type: ignore[index] + ) + + @crew + def crew(self) -> Crew: + return Crew( + agents=[ + self.researcher(), + self.reporting_analyst() + ], + tasks=[ + self.research_task(), + self.reporting_task() + ], + process=Process.sequential + ) +``` + + +Os nomes usados em seus arquivos YAML (`agents.yaml` e `tasks.yaml`) devem corresponder aos nomes dos métodos no seu código Python. + + +### Definição Direta no Código (Alternativa) + +Alternativamente, você pode definir tarefas diretamente no seu código sem usar configuração YAML: + +```python task.py +from crewai import Task + +research_task = Task( + description=""" + Realize uma pesquisa detalhada sobre AI Agents. + Certifique-se de encontrar informações interessantes e relevantes considerando + que o ano atual é 2025. + """, + expected_output=""" + Uma lista com 10 tópicos em bullet points das informações mais relevantes sobre AI Agents + """, + agent=researcher +) + +reporting_task = Task( + description=""" + Revise o contexto recebido e expanda cada tópico em uma seção completa de um relatório. + Certifique-se de que o relatório seja detalhado e contenha todas as informações relevantes. + """, + expected_output=""" + Um relatório completo com os principais tópicos, cada um com uma seção cheia de informações. + """, + agent=reporting_analyst, + markdown=True, # Ativa formatação markdown para a saída final + output_file="report.md" +) +``` + + + Especifique diretamente um `agent` para a tarefa ou permita que o processo `hierarchical` do CrewAI decida com base em papéis, disponibilidade, etc. + + +## Saída da Tarefa + +Compreender as saídas das tarefas é crucial para construir fluxos de trabalho de IA eficazes. O CrewAI oferece uma maneira estruturada de lidar com resultados usando a classe `TaskOutput`, que suporta múltiplos formatos de saída e pode ser facilmente passada entre tarefas. + +A saída de uma tarefa no framework CrewAI é encapsulada na classe `TaskOutput`. Essa classe fornece uma maneira estruturada de acessar os resultados da tarefa, incluindo vários formatos como saída bruta, JSON e modelos Pydantic. + +Por padrão, o `TaskOutput` incluirá apenas a saída `raw`. Um `TaskOutput` só terá as saídas `pydantic` ou `json_dict` se o objeto original da `Task` estiver configurado com `output_pydantic` ou `output_json`, respectivamente. + +### Atributos do Task Output + +| Atributo | Parâmetros | Tipo | Descrição | +| :---------------- | :------------- | :------------------------- | :------------------------------------------------------------------------------------------ | +| **Description** | `description` | `str` | Descrição da tarefa. | +| **Summary** | `summary` | `Optional[str]` | Resumo da tarefa, gerado automaticamente a partir das primeiras 10 palavras da descrição. | +| **Raw** | `raw` | `str` | Saída bruta da tarefa. Este é o formato padrão da saída. | +| **Pydantic** | `pydantic` | `Optional[BaseModel]` | Objeto modelo Pydantic representando a saída da tarefa de forma estruturada. | +| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]` | Dicionário representando a saída da tarefa em JSON. | +| **Agent** | `agent` | `str` | O agente que executou a tarefa. | +| **Output Format** | `output_format`| `OutputFormat` | O formato da saída da tarefa, podendo ser RAW, JSON e Pydantic. O padrão é RAW. | + +### Métodos e Propriedades da Tarefa + +| Método/Propriedade | Descrição | +| :----------------- | :--------------------------------------------------------------------------------------------- | +| **json** | Retorna a representação da saída da tarefa em JSON como string, se o formato de saída for JSON.| +| **to_dict** | Converte as saídas JSON e Pydantic para um dicionário. | +| **str** | Retorna a representação em string da saída da tarefa, priorizando Pydantic, depois JSON, depois raw. | + +### Acessando Saídas das Tarefas + +Uma vez que a tarefa é executada, sua saída pode ser acessada pelo atributo `output` do objeto `Task`. A classe `TaskOutput` oferece várias formas de interagir e apresentar esse resultado. + +#### Exemplo + +```python Code +# Exemplo de tarefa +task = Task( + description='Encontre e resuma as últimas notícias de IA', + expected_output='Uma lista em bullet points com o resumo das 5 notícias mais importantes de IA', + agent=research_agent, + tools=[search_tool] +) + +# Executando o crew +crew = Crew( + agents=[research_agent], + tasks=[task], + verbose=True +) + +result = crew.kickoff() + +# Acessando a saída da tarefa +task_output = task.output + +print(f"Descrição da Tarefa: {task_output.description}") +print(f"Resumo da Tarefa: {task_output.summary}") +print(f"Saída Bruta: {task_output.raw}") +if task_output.json_dict: + print(f"Saída em JSON: {json.dumps(task_output.json_dict, indent=2)}") +if task_output.pydantic: + print(f"Saída Pydantic: {task_output.pydantic}") +``` + +## Formatação Markdown na Saída + +O parâmetro `markdown` ativa a formatação automática em markdown na saída das tarefas. Quando configurado como `True`, a tarefa irá instruir o agente a formatar a resposta final utilizando a sintaxe Markdown correta. + +### Usando Formatação Markdown + +```python Code +# Exemplo de tarefa com formatação markdown ativada +formatted_task = Task( + description="Crie um relatório abrangente sobre tendências em IA", + expected_output="Um relatório bem estruturado com títulos, seções e bullet points", + agent=reporter_agent, + markdown=True # Habilita a formatação automática em markdown +) +``` + +Quando `markdown=True`, o agente recebe instruções extras para formatar a saída usando: +- `#` para títulos +- `**texto**` para negrito +- `*texto*` para itálico +- `-` ou `*` para bullet points +- `` `código` `` para código inline +- ``` ```linguagem ``` para blocos de código + +### Configuração YAML com Markdown + +```yaml tasks.yaml +analysis_task: + description: > + Analise os dados de mercado e crie um relatório detalhado + expected_output: > + Uma análise completa com gráficos e descobertas-chave + agent: analyst + markdown: true # Habilita formatação em markdown + output_file: analysis.md +``` + +### Benefícios da Saída Markdown + +- **Formatação Consistente**: Garante que todas as saídas sigam as convenções de markdown +- **Maior Legibilidade**: Conteúdo estruturado com títulos, listas e ênfase +- **Pronto para Documentação**: A saída pode ser usada diretamente em sistemas de documentação +- **Compatibilidade Multi-plataforma**: Markdown é universalmente suportado + + +As instruções de formatação em markdown são adicionadas automaticamente ao prompt da tarefa quando `markdown=True`, então não é necessário detalhar os requisitos de formatação na descrição da tarefa. + + +## Dependências de Tarefas e Contexto + +As tarefas podem depender da saída de outras tarefas utilizando o atributo `context`. Por exemplo: + +```python Code +research_task = Task( + description="Pesquise os últimos avanços em IA", + expected_output="Uma lista de avanços recentes em IA", + agent=researcher +) + +analysis_task = Task( + description="Analise os achados da pesquisa e identifique as tendências principais", + expected_output="Relatório de análise das tendências em IA", + agent=analyst, + context=[research_task] # Esta tarefa aguardará a conclusão da research_task +) +``` + +## Guardrails em Tarefas + +Guardrails (trilhas de proteção) de tarefas fornecem uma maneira de validar e transformar as saídas das tarefas antes que elas sejam passadas para a próxima tarefa. Esse recurso assegura a qualidade dos dados e oferece feedback aos agentes quando sua saída não atende a critérios específicos. + +### Usando Guardrails em Tarefas + +Para adicionar um guardrail a uma tarefa, forneça uma função de validação por meio do parâmetro `guardrail`: + +```python Code +from typing import Tuple, Union, Dict, Any +from crewai import TaskOutput + +def validate_blog_content(result: TaskOutput) -> Tuple[bool, Any]: + """Valida se o conteúdo do blog atende aos requisitos.""" + try: + # Verifica a contagem de palavras + word_count = len(result.split()) + if word_count > 200: + return (False, "O conteúdo do blog excede 200 palavras") + + # Lógica adicional de validação aqui + return (True, result.strip()) + except Exception as e: + return (False, "Erro inesperado durante a validação") + +blog_task = Task( + description="Escreva um post de blog sobre IA", + expected_output="Um post de blog com menos de 200 palavras", + agent=blog_agent, + guardrail=validate_blog_content # Adiciona a função guardrail +) +``` + +### Requisitos da Função Guardrail + +1. **Assinatura da Função**: + - Deve aceitar exatamente um parâmetro (a saída da tarefa) + - Deve retornar uma tupla `(bool, Any)` + - Type hints são recomendados, mas opcionais + +2. **Valores de Retorno**: + - Em caso de sucesso: retorna uma tupla `(True, resultado_validado)` + - Em caso de falha: retorna uma tupla `(False, "mensagem de erro explicando a falha")` + +### LLMGuardrail + +A classe `LLMGuardrail` oferece um mecanismo robusto para validação das saídas das tarefas. + +### Melhores Práticas de Tratamento de Erros + +1. **Respostas de Erro Estruturadas**: +```python Code +from crewai import TaskOutput, LLMGuardrail + +def validate_with_context(result: TaskOutput) -> Tuple[bool, Any]: + try: + # Lógica principal de validação + validated_data = perform_validation(result) + return (True, validated_data) + except ValidationError as e: + return (False, f"VALIDATION_ERROR: {str(e)}") + except Exception as e: + return (False, str(e)) +``` + +2. **Categorias de Erro**: + - Use códigos de erro específicos + - Inclua contexto relevante + - Forneça feedback acionável + +3. **Cadeia de Validação**: +```python Code +from typing import Any, Dict, List, Tuple, Union +from crewai import TaskOutput + +def complex_validation(result: TaskOutput) -> Tuple[bool, Any]: + """Encadeia múltiplas etapas de validação.""" + # Passo 1: Validação básica + if not result: + return (False, "Resultado vazio") + + # Passo 2: Validação de conteúdo + try: + validated = validate_content(result) + if not validated: + return (False, "Conteúdo inválido") + + # Passo 3: Validação de formato + formatted = format_output(validated) + return (True, formatted) + except Exception as e: + return (False, str(e)) +``` + +### Tratamento dos Resultados do Guardrail + +Quando um guardrail retorna `(False, erro)`: +1. O erro é enviado de volta para o agente +2. O agente tenta corrigir o problema +3. O processo se repete até: + - O guardrail retornar `(True, resultado)` + - O número máximo de tentativas ser atingido + +Exemplo com manipulação de tentativas: +```python Code +from typing import Optional, Tuple, Union +from crewai import TaskOutput, Task + +def validate_json_output(result: TaskOutput) -> Tuple[bool, Any]: + """Valida e faz o parsing da saída como JSON.""" + try: + # Tenta realizar o parsing como JSON + data = json.loads(result) + return (True, data) + except json.JSONDecodeError as e: + return (False, "Formato JSON inválido") + +task = Task( + description="Gere um relatório em JSON", + expected_output="Um objeto JSON válido", + agent=analyst, + guardrail=validate_json_output, + max_retries=3 # Limite de tentativas +) +``` + +## Obtendo Saídas Estruturadas e Consistentes das Tarefas + + +É importante também observar que a saída da última tarefa de um crew se torna a saída final do próprio crew. + + +### Usando `output_pydantic` +A propriedade `output_pydantic` permite que você defina um modelo Pydantic que a saída da tarefa deve seguir. Isso garante que a saída seja não apenas estruturada, mas também validada de acordo com o modelo. + +Veja um exemplo de uso do output_pydantic: + +```python Code +import json + +from crewai import Agent, Crew, Process, Task +from pydantic import BaseModel + + +class Blog(BaseModel): + title: str + content: str + + +blog_agent = Agent( + role="Blog Content Generator Agent", + goal="Gerar um título e conteúdo para blog", + backstory="""Você é um especialista em criação de conteúdo, habilidoso em escrever posts de blogs engajadores e informativos.""", + verbose=False, + allow_delegation=False, + llm="gpt-4o", +) + +task1 = Task( + description="""Crie um título e conteúdo para blog sobre um tópico. Certifique-se de que o conteúdo tenha menos de 200 palavras.""", + expected_output="Um título atraente e um conteúdo bem escrito para blog.", + agent=blog_agent, + output_pydantic=Blog, +) + +# Instanciando o crew com processo sequencial +crew = Crew( + agents=[blog_agent], + tasks=[task1], + verbose=True, + process=Process.sequential, +) + +result = crew.kickoff() + +# Opção 1: Acessando propriedades via indexação de dicionário +print("Acessando propriedades - Opção 1") +title = result["title"] +content = result["content"] +print("Título:", title) +print("Conteúdo:", content) + +# Opção 2: Acessando diretamente do modelo Pydantic +print("Acessando propriedades - Opção 2") +title = result.pydantic.title +content = result.pydantic.content +print("Título:", title) +print("Conteúdo:", content) + +# Opção 3: Usando o método to_dict() +print("Acessando propriedades - Opção 3") +output_dict = result.to_dict() +title = output_dict["title"] +content = output_dict["content"] +print("Título:", title) +print("Conteúdo:", content) + +# Opção 4: Imprimindo o objeto Blog inteiro +print("Acessando propriedades - Opção 5") +print("Blog:", result) + +``` +Neste exemplo: +* Um modelo Pydantic Blog é definido com os campos title e content. +* A tarefa task1 utiliza a propriedade output_pydantic para especificar que sua saída deve seguir o modelo Blog. +* Após executar o crew, você pode acessar a saída estruturada de várias formas, como mostrado. + +#### Explicação sobre o acesso à saída +1. Indexação estilo dicionário: Acesse os campos diretamente usando result["nome_do_campo"]. Isso funciona porque a classe CrewOutput implementa o método __getitem__. +2. Diretamente do modelo Pydantic: Acesse os atributos diretamente do objeto result.pydantic. +3. Usando o método to_dict(): Converta a saída para um dicionário e acesse os campos. +4. Imprimindo o objeto inteiro: Simplesmente imprima o objeto result para ver a saída estruturada. + +### Usando `output_json` +A propriedade `output_json` permite definir o formato de saída esperado em JSON. Isso garante que a saída da tarefa seja uma estrutura JSON válida que pode ser facilmente analisada e utilizada na aplicação. + +Veja um exemplo de uso do `output_json`: + +```python Code +import json + +from crewai import Agent, Crew, Process, Task +from pydantic import BaseModel + + +# Define o modelo Pydantic para o blog +class Blog(BaseModel): + title: str + content: str + + +# Define o agente +blog_agent = Agent( + role="Blog Content Generator Agent", + goal="Gerar um título e conteúdo para blog", + backstory="""Você é um especialista em criação de conteúdo, habilidoso em escrever posts de blogs engajadores e informativos.""", + verbose=False, + allow_delegation=False, + llm="gpt-4o", +) + +# Define a tarefa com output_json configurado para o modelo Blog +task1 = Task( + description="""Crie um título e conteúdo para blog sobre um tópico. Certifique-se de que o conteúdo tenha menos de 200 palavras.""", + expected_output="Um objeto JSON com os campos 'title' e 'content'.", + agent=blog_agent, + output_json=Blog, +) + +# Instancia o crew com processo sequencial +crew = Crew( + agents=[blog_agent], + tasks=[task1], + verbose=True, + process=Process.sequential, +) + +# Executa o crew para realizar a tarefa +result = crew.kickoff() + +# Opção 1: Acessando propriedades via indexação de dicionário +print("Acessando propriedades - Opção 1") +title = result["title"] +content = result["content"] +print("Título:", title) +print("Conteúdo:", content) + +# Opção 2: Imprimindo o objeto Blog inteiro +print("Acessando propriedades - Opção 2") +print("Blog:", result) +``` + +Neste exemplo: +* Um modelo Pydantic Blog é definido com os campos title e content, usado para especificar a estrutura do JSON de saída. +* A tarefa task1 utiliza a propriedade output_json para indicar que espera uma saída JSON que segue o modelo Blog. +* Após executar o crew, você pode acessar a saída estruturada em JSON conforme demonstrado. + +#### Explicação sobre o acesso à saída + +1. Acessando propriedades via indexação de dicionário: Você pode acessar os campos diretamente usando result["nome_do_campo"]. Isso é possível pois a classe CrewOutput implementa o método __getitem__, permitindo tratar a saída como um dicionário. Nesse caso, estamos acessando title e content do resultado. +2. Imprimindo o objeto Blog inteiro: Ao imprimir result, você obterá a representação em string do objeto CrewOutput. Como o método __str__ é implementado para retornar a saída em JSON, isso exibirá toda a saída como uma string formatada representando o objeto Blog. + +--- + +Utilizando `output_pydantic` ou `output_json`, você garante que suas tarefas produzam saídas em um formato estruturado e consistente, facilitando o processamento e uso dos dados na sua aplicação ou entre múltiplas tarefas. + +## Integrando Ferramentas com Tarefas + +Utilize ferramentas do [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools) e [LangChain Tools](https://python.langchain.com/docs/integrations/tools) para ampliar o desempenho das tarefas e aprimorar a interação dos agentes. + +## Criando uma Tarefa com Ferramentas + +```python Code +import os +os.environ["OPENAI_API_KEY"] = "Sua Chave" +os.environ["SERPER_API_KEY"] = "Sua Chave" # Chave serper.dev + +from crewai import Agent, Task, Crew +from crewai_tools import SerperDevTool + +research_agent = Agent( + role='Researcher', + goal='Encontrar e resumir as últimas notícias de IA', + backstory="""Você é um pesquisador em uma grande empresa. + Sua responsabilidade é analisar dados e fornecer insights + para o negócio.""", + verbose=True +) + +# Para realizar buscas semânticas de um termo a partir de textos da internet +search_tool = SerperDevTool() + +task = Task( + description='Encontre e resuma as últimas notícias de IA', + expected_output='Uma lista em bullet points com o resumo das 5 notícias mais importantes de IA', + agent=research_agent, + tools=[search_tool] +) + +crew = Crew( + agents=[research_agent], + tasks=[task], + verbose=True +) + +result = crew.kickoff() +print(result) +``` + +Isso demonstra como tarefas com ferramentas específicas podem sobrescrever o conjunto padrão de um agente para uma execução mais personalizada da tarefa. + +## Referenciando Outras Tarefas + +No CrewAI, a saída de uma tarefa é automaticamente repassada para a próxima, mas você pode definir explicitamente de quais tarefas a saída deve ser utilizada como contexto por outra, inclusive múltiplas saídas. + +É útil especialmente quando você precisa que uma tarefa dependa do resultado de outra que não é executada imediatamente antes dela. Isso é feito pelo atributo `context`: + +```python Code +# ... + +research_ai_task = Task( + description="Pesquise os avanços mais recentes em IA", + expected_output="Uma lista de avanços recentes em IA", + async_execution=True, + agent=research_agent, + tools=[search_tool] +) + +research_ops_task = Task( + description="Pesquise os avanços mais recentes em AI Ops", + expected_output="Uma lista de avanços recentes em AI Ops", + async_execution=True, + agent=research_agent, + tools=[search_tool] +) + +write_blog_task = Task( + description="Escreva um post de blog completo sobre a importância da IA e suas últimas notícias", + expected_output="Post de blog completo com 4 parágrafos", + agent=writer_agent, + context=[research_ai_task, research_ops_task] +) + +#... +``` + +## Execução Assíncrona + +Você pode definir que uma tarefa seja executada de forma assíncrona. Isso significa que o crew não aguardará sua conclusão para seguir para a próxima tarefa. É útil para tarefas demoradas, ou que não são cruciais para as seguintes. + +Depois, utilize o atributo `context` para indicar, em uma tarefa futura, que ela deve aguardar os resultados da tarefa assíncrona. + +```python Code +#... + +list_ideas = Task( + description="Liste 5 ideias interessantes para explorar em um artigo sobre IA.", + expected_output="Lista em bullet points com 5 ideias para um artigo.", + agent=researcher, + async_execution=True # Será executada de forma assíncrona +) + +list_important_history = Task( + description="Pesquise a história da IA e forneça os 5 eventos mais importantes.", + expected_output="Lista em bullet points com 5 eventos importantes.", + agent=researcher, + async_execution=True # Será executada de forma assíncrona +) + +write_article = Task( + description="Escreva um artigo sobre IA, sua história e ideias interessantes.", + expected_output="Artigo de 4 parágrafos sobre IA.", + agent=writer, + context=[list_ideas, list_important_history] # Vai esperar o resultado das duas tarefas +) + +#... +``` + +## Mecanismo de Callback + +A função callback é executada após a conclusão da tarefa, permitindo acionar ações ou notificações baseadas no resultado da tarefa. + +```python Code +# ... + +def callback_function(output: TaskOutput): + # Realiza algo após a conclusão da tarefa + # Exemplo: Envia um e-mail ao gerente + print(f""" + Tarefa concluída! + Tarefa: {output.description} + Saída: {output.raw} + """) + +research_task = Task( + description='Encontre e resuma as últimas notícias de IA', + expected_output='Uma lista em bullet points com o resumo das 5 notícias mais importantes de IA', + agent=research_agent, + tools=[search_tool], + callback=callback_function +) + +#... +``` + +## Acessando a Saída de uma Tarefa Específica + +Assim que um crew finaliza sua execução, você pode acessar a saída de uma tarefa específica por meio do atributo `output` do objeto da tarefa: + +```python Code +# ... +task1 = Task( + description='Encontre e resuma as últimas notícias de IA', + expected_output='Uma lista em bullet points com o resumo das 5 notícias mais importantes de IA', + agent=research_agent, + tools=[search_tool] +) + +#... + +crew = Crew( + agents=[research_agent], + tasks=[task1, task2, task3], + verbose=True +) + +result = crew.kickoff() + +# Retorna um objeto TaskOutput com a descrição e resultado da tarefa +print(f""" + Tarefa concluída! + Tarefa: {task1.output.description} + Saída: {task1.output.raw} +""") +``` + +## Mecanismo de Sobrescrição de Ferramentas + +Especificar ferramentas em uma tarefa permite a adaptação dinâmica das capacidades do agente, destacando a flexibilidade do CrewAI. + +## Mecanismos de Validação e Tratamento de Erros + +Ao criar e executar tarefas, determinados mecanismos de validação garantem a robustez e confiabilidade dos atributos das tarefas. Isso inclui, mas não se limita a: + +- Garantir que apenas um tipo de saída seja definido por tarefa para manter expectativas de saída claras. +- Impedir a atribuição manual do atributo `id`, preservando a integridade do sistema de identificadores únicos. + +Estas validações colaboram para a consistência e confiabilidade das execuções de tarefas no framework CrewAI. + +## Guardrails em Tarefas + +Guardrails de tarefas oferecem uma maneira poderosa de validar, transformar ou filtrar as saídas das tarefas antes de serem encaminhadas à próxima. São funções opcionais que executam antes do início da próxima tarefa, garantindo que as saídas estejam em conformidade com requisitos ou formatos esperados. + +### Uso Básico + +#### Defina sua própria lógica de validação + +```python Code +from typing import Tuple, Union +from crewai import Task + +def validate_json_output(result: str) -> Tuple[bool, Union[dict, str]]: + """Valida se a saída é um JSON válido.""" + try: + json_data = json.loads(result) + return (True, json_data) + except json.JSONDecodeError: + return (False, "A saída deve ser um JSON válido") + +task = Task( + description="Gerar dados em JSON", + expected_output="Objeto JSON válido", + guardrail=validate_json_output +) +``` + +#### Use uma abordagem no-code para validação + +```python Code +from crewai import Task + +task = Task( + description="Gerar dados em JSON", + expected_output="Objeto JSON válido", + guardrail="Garanta que a resposta é um objeto JSON válido" +) +``` + +#### Usando YAML + +```yaml +research_task: + ... + guardrail: garanta que cada bullet tenha no mínimo 100 palavras + ... +``` + +```python Code +@CrewBase +class InternalCrew: + agents_config = "config/agents.yaml" + tasks_config = "config/tasks.yaml" + + ... + @task + def research_task(self): + return Task(config=self.tasks_config["research_task"]) # type: ignore[index] + ... +``` + +#### Use modelos customizados para geração de código + +```python Code +from crewai import Task +from crewai.llm import LLM + +task = Task( + description="Gerar dados em JSON", + expected_output="Objeto JSON válido", + guardrail=LLMGuardrail( + description="Garanta que a resposta é um objeto JSON válido", + llm=LLM(model="gpt-4o-mini"), + ) +) +``` + +### Como Guardrails Funcionam + +1. **Atributo Opcional**: Guardrails são opcionais por tarefa, permitindo adicionar validação só onde for necessário. +2. **Momento de Execução**: A função guardrail é executada antes do início da próxima tarefa, garantindo fluxo de dados válido entre tarefas. +3. **Formato de Retorno**: Guardrails devem retornar uma tupla `(sucesso, dados)`: + - Se `sucesso` é `True`, `dados` é o resultado validado/transformado + - Se `sucesso` é `False`, `dados` é a mensagem de erro +4. **Roteamento do Resultado**: + - Sucesso (`True`): o resultado é automaticamente passado para a próxima tarefa + - Falha (`False`): o erro é enviado de volta ao agente para gerar uma nova resposta + +### Casos Comuns de Uso + +#### Validação de Formato de Dados +```python Code +def validate_email_format(result: str) -> Tuple[bool, Union[str, str]]: + """Garante que a saída contenha um e-mail válido.""" + import re + email_pattern = r'^[\w\.-]+@[\w\.-]+\.\w+$' + if re.match(email_pattern, result.strip()): + return (True, result.strip()) + return (False, "A saída deve ser um e-mail válido") +``` + +#### Filtragem de Conteúdo +```python Code +def filter_sensitive_info(result: str) -> Tuple[bool, Union[str, str]]: + """Remove ou valida informações sensíveis.""" + sensitive_patterns = ['SSN:', 'password:', 'secret:'] + for pattern in sensitive_patterns: + if pattern.lower() in result.lower(): + return (False, f"A saída contém informação sensível ({pattern})") + return (True, result) +``` + +#### Transformação de Dados +```python Code +def normalize_phone_number(result: str) -> Tuple[bool, Union[str, str]]: + """Garante que números de telefone estejam em formato consistente.""" + import re + digits = re.sub(r'\D', '', result) + if len(digits) == 10: + formatted = f"({digits[:3]}) {digits[3:6]}-{digits[6:]}" + return (True, formatted) + return (False, "A saída deve ser um telefone com 10 dígitos") +``` + +### Recursos Avançados + +#### Encadeando Múltiplas Validações +```python Code +def chain_validations(*validators): + """Encadeia múltiplos validadores.""" + def combined_validator(result): + for validator in validators: + success, data = validator(result) + if not success: + return (False, data) + result = data + return (True, result) + return combined_validator + +# Uso +task = Task( + description="Obtenha informações de contato do usuário", + expected_output="E-mail e telefone", + guardrail=chain_validations( + validate_email_format, + filter_sensitive_info + ) +) +``` + +#### Lógica Customizada de Retentativas +```python Code +task = Task( + description="Gerar dados", + expected_output="Dados válidos", + guardrail=validate_data, + max_retries=5 # Sobrescreve o limite padrão de tentativas +) +``` + +## Criando Diretórios ao Salvar Arquivos + +Agora é possível especificar se uma tarefa deve criar diretórios ao salvar sua saída em arquivo. Isso é útil para organizar outputs e garantir que os caminhos estejam corretos. + +```python Code +# ... + +save_output_task = Task( + description='Salve o resumo das notícias de IA em um arquivo', + expected_output='Arquivo salvo com sucesso', + agent=research_agent, + tools=[file_save_tool], + output_file='outputs/ai_news_summary.txt', + create_directory=True +) + +#... +``` + +Veja o vídeo abaixo para aprender como utilizar saídas estruturadas no CrewAI: + + + +## Conclusão + +Tarefas são a força motriz por trás das ações dos agentes no CrewAI. +Ao definir corretamente as tarefas e seus resultados, você prepara seus agentes de IA para trabalhar de forma eficaz, seja de forma independente ou colaborativa. +Equipar tarefas com as ferramentas adequadas, compreender o processo de execução e seguir práticas sólidas de validação são fundamentais para maximizar o potencial do CrewAI, +assegurando que os agentes estejam devidamente preparados para suas atribuições e que as tarefas sejam executadas conforme o esperado. diff --git a/docs/pt-BR/concepts/testing.mdx b/docs/pt-BR/concepts/testing.mdx new file mode 100644 index 000000000..96e84c415 --- /dev/null +++ b/docs/pt-BR/concepts/testing.mdx @@ -0,0 +1,48 @@ +--- +title: Testes +description: Saiba como testar sua CrewAI Crew e avaliar seu desempenho. +icon: vial +--- + +## Visão Geral + +Testar é uma parte crucial do processo de desenvolvimento, sendo essencial para garantir que sua crew está performando conforme o esperado. Com o crewAI, você pode facilmente testar sua crew e avaliar seu desempenho utilizando as funcionalidades de teste integradas. + +### Utilizando o Recurso de Teste + +Adicionamos o comando de CLI `crewai test` para facilitar o teste da sua crew. Esse comando executará sua crew por um número especificado de iterações e fornecerá métricas de desempenho detalhadas. Os parâmetros são `n_iterations` e `model`, ambos opcionais e com valores padrão de 2 e `gpt-4o-mini`, respectivamente. Por enquanto, o único provedor disponível é a OpenAI. + +```bash +crewai test +``` + +Se quiser rodar mais iterações ou utilizar um modelo diferente, você pode especificar os parâmetros assim: + +```bash +crewai test --n_iterations 5 --model gpt-4o +``` + +ou usando as formas abreviadas: + +```bash +crewai test -n 5 -m gpt-4o +``` + +Ao executar o comando `crewai test`, a crew será executada pelo número especificado de iterações, e as métricas de desempenho serão exibidas ao final da execução. + +Uma tabela de pontuações ao final mostrará o desempenho da crew em relação às seguintes métricas: + +
**Pontuações das Tarefas (1-10, quanto maior melhor)**
+ +| 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. \ No newline at end of file diff --git a/docs/pt-BR/concepts/tools.mdx b/docs/pt-BR/concepts/tools.mdx new file mode 100644 index 000000000..da8069bc1 --- /dev/null +++ b/docs/pt-BR/concepts/tools.mdx @@ -0,0 +1,283 @@ +--- +title: Ferramentas +description: Compreendendo e aproveitando ferramentas dentro do framework CrewAI para colaboração e execução de tarefas por agentes. +icon: screwdriver-wrench +--- + +## Visão geral + +As ferramentas do CrewAI capacitam agentes com habilidades que vão desde busca na web e análise de dados até colaboração e delegação de tarefas entre colegas de trabalho. +Esta documentação descreve como criar, integrar e aproveitar essas ferramentas dentro do framework CrewAI, incluindo um novo foco em ferramentas de colaboração. + +## O que é uma Ferramenta? + +Uma ferramenta no CrewAI é uma habilidade ou função que os agentes podem utilizar para executar diversas ações. +Isso inclui ferramentas do [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools) e [LangChain Tools](https://python.langchain.com/docs/integrations/tools), +permitindo desde buscas simples até interações complexas e trabalho em equipe eficiente entre agentes. + + +O CrewAI Enterprise oferece um Repositório de Ferramentas abrangente, com integrações pré-construídas para sistemas empresariais e APIs comuns. Implemente agentes com ferramentas corporativas em minutos em vez de dias. + +O Repositório de Ferramentas Empresariais inclui: +- Conectores pré-construídos para sistemas empresariais populares +- Interface para criação de ferramentas personalizadas +- Controle de versão e funcionalidades de compartilhamento +- Recursos de segurança e conformidade + + +## Características Principais das Ferramentas + +- **Utilidade**: Desenvolvidas para tarefas como busca web, análise de dados, geração de conteúdo e colaboração entre agentes. +- **Integração**: Potencializa as habilidades dos agentes ao integrar ferramentas de forma transparente ao seu fluxo de trabalho. +- **Personalização**: Oferece flexibilidade para desenvolver ferramentas personalizadas ou utilizar existentes, atendendo necessidades específicas dos agentes. +- **Tratamento de Erros**: Incorpora mecanismos robustos de tratamento de erros para garantir operação sem interrupções. +- **Mecanismo de Cache**: Possui cache inteligente para otimizar desempenho e reduzir operações redundantes. +- **Suporte Assíncrono**: Suporta ferramentas síncronas e assíncronas, permitindo operações não bloqueantes. + +## Utilizando Ferramentas CrewAI + +Para aprimorar as capacidades de seus agentes com as ferramentas do CrewAI, comece instalando nosso pacote extra de ferramentas: + +```bash +pip install 'crewai[tools]' +``` + +Aqui está um exemplo demonstrando seu uso: + +```python Code +import os +from crewai import Agent, Task, Crew +# Importando ferramentas do crewAI +from crewai_tools import ( + DirectoryReadTool, + FileReadTool, + SerperDevTool, + WebsiteSearchTool +) + +# Configure as chaves de API +os.environ["SERPER_API_KEY"] = "Your Key" # chave da API serper.dev +os.environ["OPENAI_API_KEY"] = "Your Key" + +# Instanciar as ferramentas +docs_tool = DirectoryReadTool(directory='./blog-posts') +file_tool = FileReadTool() +search_tool = SerperDevTool() +web_rag_tool = WebsiteSearchTool() + +# Criar agentes +researcher = Agent( + role='Market Research Analyst', + goal='Provide up-to-date market analysis of the AI industry', + backstory='An expert analyst with a keen eye for market trends.', + tools=[search_tool, web_rag_tool], + verbose=True +) + +writer = Agent( + role='Content Writer', + goal='Craft engaging blog posts about the AI industry', + backstory='A skilled writer with a passion for technology.', + tools=[docs_tool, file_tool], + verbose=True +) + +# Definir tarefas +research = Task( + description='Research the latest trends in the AI industry and provide a summary.', + expected_output='A summary of the top 3 trending developments in the AI industry with a unique perspective on their significance.', + agent=researcher +) + +write = Task( + description='Write an engaging blog post about the AI industry, based on the research analyst's summary. Draw inspiration from the latest blog posts in the directory.', + expected_output='A 4-paragraph blog post formatted in markdown with engaging, informative, and accessible content, avoiding complex jargon.', + agent=writer, + output_file='blog-posts/new_post.md' # O post final do blog será salvo aqui +) + +# Montar um crew com o planejamento habilitado +crew = Crew( + agents=[researcher, writer], + tasks=[research, write], + verbose=True, + planning=True, # Habilitar o recurso de planejamento +) + +# Executar tarefas +crew.kickoff() +``` + +## Ferramentas CrewAI Disponíveis + +- **Tratamento de Erros**: Todas as ferramentas são construídas com capacidades de tratamento de erros, permitindo que os agentes administrem exceções de forma adequada e prossigam com suas tarefas. +- **Mecanismo de Cache**: Todas as ferramentas suportam cache, possibilitando que agentes reutilizem de forma eficiente resultados obtidos anteriormente, reduzindo a carga em recursos externos e acelerando o tempo de execução. Também é possível definir controles mais precisos sobre o mecanismo de cache usando o atributo `cache_function` na ferramenta. + +Aqui está uma lista das ferramentas disponíveis e suas descrições: + +| Ferramenta | Descrição | +| :------------------------------- | :------------------------------------------------------------------------------------------- | +| **ApifyActorsTool** | Ferramenta que integra Apify Actors aos seus fluxos de trabalho para web scraping e automação.| +| **BrowserbaseLoadTool** | Ferramenta para interação e extração de dados de navegadores web. | +| **CodeDocsSearchTool** | Uma ferramenta RAG otimizada para busca em documentações de código e documentos técnicos. | +| **CodeInterpreterTool** | Ferramenta para interpretar código Python. | +| **ComposioTool** | Permite o uso de ferramentas Composio. | +| **CSVSearchTool** | Ferramenta RAG projetada para busca em arquivos CSV, ideal para dados estruturados. | +| **DALL-E Tool** | Ferramenta para gerar imagens utilizando a API do DALL-E. | +| **DirectorySearchTool** | Ferramenta RAG para busca em diretórios, útil para navegação em sistemas de arquivos. | +| **DOCXSearchTool** | Ferramenta RAG voltada para busca em documentos DOCX, ideal para processar arquivos Word. | +| **DirectoryReadTool** | Facilita a leitura e processamento de estruturas de diretórios e seus conteúdos. | +| **EXASearchTool** | Ferramenta projetada para buscas exaustivas em diversas fontes de dados. | +| **FileReadTool** | Permite a leitura e extração de dados de arquivos, suportando diversos formatos. | +| **FirecrawlSearchTool** | Ferramenta para buscar páginas web usando Firecrawl e retornar os resultados. | +| **FirecrawlCrawlWebsiteTool** | Ferramenta para rastrear páginas web utilizando o Firecrawl. | +| **FirecrawlScrapeWebsiteTool** | Ferramenta para extrair o conteúdo de URLs usando Firecrawl. | +| **GithubSearchTool** | Ferramenta RAG para buscar em repositórios GitHub, útil para pesquisa de código e documentação.| +| **SerperDevTool** | Ferramenta especializada para finalidades de desenvolvimento, com funcionalidades em evolução. | +| **TXTSearchTool** | Ferramenta RAG voltada para busca em arquivos de texto (.txt), adaptada para dados não estruturados. | +| **JSONSearchTool** | Ferramenta RAG para busca em arquivos JSON, voltada ao manuseio de dados estruturados. | +| **LlamaIndexTool** | Permite o uso das ferramentas LlamaIndex. | +| **MDXSearchTool** | Ferramenta RAG para busca em arquivos Markdown (MDX), útil para documentação. | +| **PDFSearchTool** | Ferramenta RAG para busca em documentos PDF, ideal para processar documentos digitalizados. | +| **PGSearchTool** | Ferramenta RAG otimizada para busca em bancos de dados PostgreSQL, adequada para consultas. | +| **Vision Tool** | Ferramenta para gerar imagens utilizando a API do DALL-E. | +| **RagTool** | Ferramenta RAG de uso geral, capaz de lidar com diferentes fontes e tipos de dados. | +| **ScrapeElementFromWebsiteTool** | Permite extrair elementos específicos de sites, útil para extração de dados direcionada. | +| **ScrapeWebsiteTool** | Facilita o scraping de sites inteiros, ideal para coleta abrangente de dados. | +| **WebsiteSearchTool** | Ferramenta RAG para busca em conteúdos de sites, otimizada para extração de dados web. | +| **XMLSearchTool** | Ferramenta RAG para busca em arquivos XML, adequada para formatos de dados estruturados. | +| **YoutubeChannelSearchTool** | Ferramenta RAG para busca em canais do YouTube, útil para análise de conteúdo em vídeo. | +| **YoutubeVideoSearchTool** | Ferramenta RAG para busca em vídeos do YouTube, ideal para extração de dados de vídeo. | + +## Criando suas próprias Ferramentas + + + Desenvolvedores podem criar `ferramentas personalizadas` adaptadas para as necessidades de seus agentes ou utilizar opções pré-construídas. + + +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 + + + 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. + + +```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. \ No newline at end of file diff --git a/docs/pt-BR/concepts/training.mdx b/docs/pt-BR/concepts/training.mdx new file mode 100644 index 000000000..ca98005e8 --- /dev/null +++ b/docs/pt-BR/concepts/training.mdx @@ -0,0 +1,66 @@ +--- +title: Treinamento +description: Aprenda como treinar seus agentes CrewAI fornecendo feedback desde o início e obtenha resultados consistentes. +icon: dumbbell +--- + +## Visão Geral + +O recurso de treinamento no CrewAI permite que você treine seus agentes de IA usando a interface de linha de comando (CLI). +Ao executar o comando `crewai train -n `, 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 (optional) +``` + + Substitua `` pelo número desejado de iterações de treinamento e `` pelo nome de arquivo apropriado terminando com `.pkl`. + + +### Treinando sua Crew Programaticamente + +Para treinar sua crew de forma programática, siga estes passos: + +1. Defina o número de iterações para o treinamento. +2. Especifique os parâmetros de entrada para o processo de treinamento. +3. Execute o comando de treinamento dentro de um bloco try-except para tratar possíveis erros. + +```python Code +n_iterations = 2 +inputs = {"topic": "CrewAI Training"} +filename = "your_model.pkl" + +try: + YourCrewName_Crew().crew().train( + n_iterations=n_iterations, + inputs=inputs, + filename=filename + ) + +except Exception as e: + raise Exception(f"An error occurred while training the crew: {e}") +``` + +### Pontos Importantes + +- **Requisito de Número Inteiro Positivo:** Certifique-se de que o número de iterações (`n_iterations`) seja um inteiro positivo. O código lançará um `ValueError` se essa condição não for atendida. +- **Requisito de Nome de Arquivo:** Certifique-se de que o nome do arquivo termine com `.pkl`. O código lançará um `ValueError` se essa condição não for atendida. +- **Tratamento de Erros:** O código trata erros de subprocessos e exceções inesperadas, fornecendo mensagens de erro ao usuário. + +É importante observar que o processo de treinamento pode levar algum tempo, dependendo da complexidade dos seus agentes e também exigirá seu feedback em cada iteração. + +Uma vez concluído o treinamento, seus agentes estarão equipados com capacidades e conhecimentos aprimorados, prontos para enfrentar tarefas complexas e fornecer insights mais consistentes e valiosos. + +Lembre-se de atualizar e treinar seus agentes regularmente para garantir que permaneçam atualizados com as últimas informações e avanços na área. + +Bom treinamento com o CrewAI! 🚀 \ No newline at end of file diff --git a/docs/pt-BR/enterprise/features/hallucination-guardrail.mdx b/docs/pt-BR/enterprise/features/hallucination-guardrail.mdx new file mode 100644 index 000000000..5cdfab77a --- /dev/null +++ b/docs/pt-BR/enterprise/features/hallucination-guardrail.mdx @@ -0,0 +1,250 @@ +--- +title: Proteção contra Alucinações +description: "Previna e detecte alucinações de IA nas suas tarefas do CrewAI" +icon: "shield-check" +--- + +## Visão Geral + +A Proteção contra Alucinações é um recurso empresarial que valida o conteúdo gerado por IA para garantir que esteja fundamentado em fatos e não contenha alucinações. Ela analisa as saídas das tarefas em relação ao contexto de referência e fornece feedback detalhado quando é detectado conteúdo potencialmente alucinado. + +## O que são Alucinações? + +Alucinações em IA ocorrem quando modelos de linguagem geram conteúdos que parecem plausíveis, mas estão factualmente incorretos ou não são suportados pelo contexto fornecido. A Proteção contra Alucinações ajuda a prevenir esses problemas por meio de: + +- Comparação das saídas com o contexto de referência +- Avaliação da fidelidade ao material de origem +- Fornecimento de feedback detalhado sobre conteúdo problemático +- Suporte a limiares personalizados para rigor da validação + +## Uso Básico + +### Configurando a Proteção + +```python +from crewai.tasks.hallucination_guardrail import HallucinationGuardrail +from crewai import LLM + +# Uso básico - utiliza o expected_output da tarefa como contexto +guardrail = HallucinationGuardrail( + llm=LLM(model="gpt-4o-mini") +) + +# Com contexto de referência explícito +context_guardrail = HallucinationGuardrail( + context="AI helps with various tasks including analysis and generation.", + llm=LLM(model="gpt-4o-mini") +) +``` + +### Adicionando às Tarefas + +```python +from crewai import Task + +# Crie sua tarefa com a proteção +task = Task( + description="Write a summary about AI capabilities", + expected_output="A factual summary based on the provided context", + agent=my_agent, + guardrail=guardrail # Adiciona a proteção para validar a saída +) +``` + +## Configuração Avançada + +### Validação com Limiar Personalizado + +Para validação mais rigorosa, é possível definir um limiar de fidelidade personalizado (escala de 0-10): + +```python +# Proteção rigorosa exigindo alta pontuação de fidelidade +strict_guardrail = HallucinationGuardrail( + context="Quantum computing uses qubits that exist in superposition states.", + llm=LLM(model="gpt-4o-mini"), + threshold=8.0 # Requer pontuação >= 8 para validar +) +``` + +### Incluindo Contexto da Resposta de Ferramentas + +Se sua tarefa utiliza ferramentas, você pode incluir as respostas das ferramentas para validação mais precisa: + +```python +# Proteção com contexto de resposta da ferramenta +weather_guardrail = HallucinationGuardrail( + context="Current weather information for the requested location", + llm=LLM(model="gpt-4o-mini"), + tool_response="Weather API returned: Temperature 22°C, Humidity 65%, Clear skies" +) +``` + +## Como Funciona + +### Processo de Validação + +1. **Análise de Contexto**: A proteção compara a saída da tarefa com o contexto de referência fornecido +2. **Pontuação de Fidelidade**: Usa um avaliador interno para atribuir uma pontuação de fidelidade (0-10) +3. **Determinação do Veredito**: Determina se o conteúdo é fiel ou contém alucinações +4. **Verificação de Limiar**: Se um limiar personalizado for definido, valida contra essa pontuação +5. **Geração de Feedback**: Fornece motivos detalhados caso a validação falhe + +### Lógica de Validação + +- **Modo Padrão**: Utiliza validação baseada em veredito (FIÉL vs ALUCINADO) +- **Modo com Limiar**: Requer que a pontuação de fidelidade atinja ou supere o limiar especificado +- **Tratamento de Erros**: Lida com erros de avaliação de forma elegante e fornece feedback informativo + +## Resultados da Proteção + +A proteção retorna resultados estruturados indicando o status da validação: + +```python +# Exemplo de estrutura de resultado da proteção +{ + "valid": False, + "feedback": "Content appears to be hallucinated (score: 4.2/10, verdict: HALLUCINATED). The output contains information not supported by the provided context." +} +``` + +### Propriedades do Resultado + +- **valid**: Booleano indicando se a saída passou na validação +- **feedback**: Explicação detalhada quando a validação falha, incluindo: + - Pontuação de fidelidade + - Classificação do veredito + - Motivos específicos para a falha + +## Integração com o Sistema de Tarefas + +### Validação Automática + +Quando uma proteção é adicionada à tarefa, ela valida automaticamente a saída antes da tarefa ser marcada como concluída: + +```python +# Fluxo de validação de saída da tarefa +task_output = agent.execute_task(task) +validation_result = guardrail(task_output) + +if validation_result.valid: + # Tarefa concluída com sucesso + return task_output +else: + # Tarefa falha com feedback de validação + raise ValidationError(validation_result.feedback) +``` + +### Rastreamento de Eventos + +A proteção se integra ao sistema de eventos do CrewAI para fornecer observabilidade: + +- **Validação Iniciada**: Quando a avaliação da proteção começa +- **Validação Concluída**: Quando a avaliação termina com resultados +- **Falha na Validação**: Quando ocorrem erros técnicos durante a avaliação + +## Melhores Práticas + +### Diretrizes para o Contexto + + + + Inclua todas as informações factuais relevantes nas quais a IA deve basear sua saída: + + ```python + context = """ + Company XYZ was founded in 2020 and specializes in renewable energy solutions. + They have 150 employees and generated $50M revenue in 2023. + Their main products include solar panels and wind turbines. + """ + ``` + + + + Inclua apenas informações diretamente relacionadas à tarefa para evitar confusão: + + ```python + # Bom: Contexto focado + context = "The current weather in New York is 18°C with light rain." + + # Evite: Informações irrelevantes + context = "The weather is 18°C. The city has 8 million people. Traffic is heavy." + ``` + + + + Certifique-se de que seu contexto de referência reflita informações atuais e precisas. + + + +### Seleção de Limiar + + + + Inicie sem limiares personalizados para entender a performance inicial. + + + + - **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 + + + + Acompanhe os resultados da validação e ajuste os limiares conforme falsos positivos/negativos. + + + +## 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 + + + **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 + + + + **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 + + + + **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 + + + + Entre em contato com nosso suporte para assistência na configuração ou solução de problemas da proteção contra alucinações. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/features/integrations.mdx b/docs/pt-BR/enterprise/features/integrations.mdx new file mode 100644 index 000000000..8cfd6a208 --- /dev/null +++ b/docs/pt-BR/enterprise/features/integrations.mdx @@ -0,0 +1,179 @@ +--- +title: Integrações +description: "Aplicativos conectados para que seus agentes possam tomar ações." +icon: "plug" +--- + +## Visão Geral + +Permita que seus agentes autentiquem com qualquer provedor habilitado para OAuth e tomem ações. Do Salesforce e HubSpot ao Google e GitHub, você conta com mais de 16 serviços integrados. + + + ![Integrações](/images/enterprise/crew_connectors.png) + + +## Integrações Suportadas + +### **Comunicação & Colaboração** +- **Gmail** - Gerencie e-mails e rascunhos +- **Slack** - Notificações e alertas do workspace +- **Microsoft** - Integração com Office 365 e Teams + +### **Gerenciamento de Projetos** +- **Jira** - Rastreamento de issues e gerenciamento de projetos +- **ClickUp** - Gerenciamento de tarefas e produtividade +- **Asana** - Coordenação de tarefas e projetos de equipe +- **Notion** - Gerenciamento de páginas e bases de dados +- **Linear** - Gerenciamento de projetos de software e bugs +- **GitHub** - Gerenciamento de repositórios e issues + +### **Gestão de Relacionamento com o Cliente** +- **Salesforce** - Gerenciamento de contas e oportunidades de CRM +- **HubSpot** - Gestão de pipeline de vendas e contatos +- **Zendesk** - Administração de chamados de suporte ao cliente + +### **Negócios & Finanças** +- **Stripe** - Processamento de pagamentos e gerenciamento de clientes +- **Shopify** - Gestão de loja de e-commerce e produtos + +### **Produtividade & Armazenamento** +- **Google Sheets** - Sincronização de dados de planilhas +- **Google Calendar** - Gerenciamento de eventos e agendas +- **Box** - Armazenamento de arquivos e gerenciamento de documentos + +e mais estão por vir! + +## Pré-requisitos + +Antes de usar as Integrações de Autenticação, certifique-se de que você possui: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com). Você pode começar com uma avaliação gratuita. + +## Configurando Integrações + +### 1. Conecte sua Conta + +1. Acesse o [CrewAI Enterprise](https://app.crewai.com) +2. Vá até a aba **Integrações** - https://app.crewai.com/crewai_plus/connectors +3. Clique em **Conectar** no serviço desejado na seção Integrações de Autenticação +4. Complete o fluxo de autenticação OAuth +5. Conceda as permissões necessárias para seu caso de uso +6. Obtenha seu Token Enterprise na sua página de conta do [CrewAI Enterprise](https://app.crewai.com) - https://app.crewai.com/crewai_plus/settings/account + + + ![Integrações](/images/enterprise/enterprise_action_auth_token.png) + + +### 2. Instale as Ferramentas de Integração + +Tudo o que você precisa é da versão mais recente do pacote `crewai-tools`. + +```bash +uv add crewai-tools +``` + +## Exemplos de Uso + +### Uso Básico + + Todos os serviços nos quais você estiver autenticado estarão disponíveis como ferramentas. Portanto, tudo que você precisa fazer é adicionar o `CrewaiEnterpriseTools` ao seu agente e pronto. + + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Obtenha ferramentas enterprise (a ferramenta Gmail será incluída) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) +# imprima as ferramentas +print(enterprise_tools) + +# Crie um agente com capacidades do Gmail +email_agent = Agent( + role="Email Manager", + goal="Manage and organize email communications", + backstory="An AI assistant specialized in email management and communication.", + tools=enterprise_tools +) + +# Tarefa para enviar um e-mail +email_task = Task( + description="Draft and send a follow-up email to john@example.com about the project update", + agent=email_agent, + expected_output="Confirmation that email was sent successfully" +) + +# Execute a tarefa +crew = Crew( + agents=[email_agent], + tasks=[email_task] +) + +# Execute o crew +crew.kickoff() +``` + +### Filtrando Ferramentas + +```python +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + actions_list=["gmail_find_email"] # apenas a ferramenta gmail_find_email estará disponível +) +gmail_tool = enterprise_tools["gmail_find_email"] + +gmail_agent = Agent( + role="Gmail Manager", + goal="Manage gmail communications and notifications", + backstory="An AI assistant that helps coordinate gmail communications.", + tools=[gmail_tool] +) + +notification_task = Task( + description="Find the email from john@example.com", + agent=gmail_agent, + expected_output="Email found from john@example.com" +) + +# Execute a tarefa +crew = Crew( + agents=[slack_agent], + tasks=[notification_task] +) +``` + +## Melhores Práticas + +### Segurança +- **Princípio do Menor Privilégio**: Conceda apenas as permissões mínimas exigidas para as tarefas dos seus agentes +- **Auditorias Regulares**: Revise periodicamente as integrações conectadas e suas permissões +- **Credenciais Seguras**: Nunca insira credenciais diretamente no código; utilize o fluxo seguro de autenticação do CrewAI + +### Filtrando Ferramentas +Em um crew implantado, você pode especificar quais ações estão disponíveis para cada integração a partir da página de configurações do serviço ao qual você se conectou. + + + ![Integrações](/images/enterprise/filtering_enterprise_action_tools.png) + + +### Implantações com Escopo para organizações multiusuário +Você pode implantar seu crew e associar cada integração a um usuário específico. Por exemplo, um crew que se conecta ao Google pode usar a conta do Gmail de um usuário específico. + + + Isso é útil para organizações multiusuário, onde você deseja direcionar a integração para um usuário específico. + + +Use o `user_bearer_token` para direcionar a integração a um usuário específico; assim, quando o crew for iniciado, ele usará o bearer token desse usuário para autenticar com a integração. Se o usuário não estiver logado, o crew não utilizará nenhuma integração conectada. Use o bearer token padrão para autenticar com as integrações que estão sendo implantadas com o crew. + + + ![Integrações](/images/enterprise/user_bearer_token.png) + + +### Precisa de Ajuda? + + + Entre em contato com nosso time de suporte para assistência com a configuração de integrações ou solução de problemas. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/features/tool-repository.mdx b/docs/pt-BR/enterprise/features/tool-repository.mdx new file mode 100644 index 000000000..e3616a2b5 --- /dev/null +++ b/docs/pt-BR/enterprise/features/tool-repository.mdx @@ -0,0 +1,107 @@ +--- +title: Repositório de Ferramentas +description: "Usando o Repositório de Ferramentas para gerenciar suas ferramentas" +icon: "toolbox" +--- + +## Visão geral + +O Repositório de Ferramentas é um gerenciador de pacotes para ferramentas da CrewAI. Ele permite que usuários publiquem, instalem e gerenciem ferramentas que se integram com crews e flows da CrewAI. + +As ferramentas podem ser: + +- **Privadas**: acessíveis apenas dentro da sua organização (padrão) +- **Públicas**: acessíveis a todos os usuários CrewAI se publicadas com a flag `--public` + +O repositório não é um sistema de controle de versões. Use o Git para rastrear mudanças no código e permitir colaboração. + +## Pré-requisitos + +Antes de usar o Repositório de Ferramentas, certifique-se de que você possui: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) +- [CrewAI CLI](https://docs.crewai.com/concepts/cli#cli) instalada +- uv>=0.5.0 instalado. Veja [como atualizar](https://docs.astral.sh/uv/getting-started/installation/#upgrading-uv) +- [Git](https://git-scm.com) instalado e configurado +- Permissões de acesso para publicar ou instalar ferramentas em sua organização CrewAI Enterprise + +## Instalando ferramentas + +Para instalar uma ferramenta: + +```bash +crewai tool install +``` + +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 +``` + +Isso gera um projeto de ferramenta estruturado localmente. + +Após fazer alterações, inicialize um repositório Git e faça o commit do código: + +```bash +git init +git add . +git commit -m "Initial version" +``` + +Para publicar a ferramenta: + +```bash +crewai tool publish +``` + +Por padrão, as ferramentas são publicadas como privadas. Para tornar uma ferramenta pública: + +```bash +crewai tool publish --public +``` + +Para mais detalhes sobre como construir ferramentas, acesse [Criando suas próprias ferramentas](https://docs.crewai.com/concepts/tools#creating-your-own-tools). + +## Atualizando ferramentas + +Para atualizar uma ferramenta publicada: + +1. Modifique a ferramenta localmente +2. Atualize a versão no `pyproject.toml` (por exemplo, de `0.1.0` para `0.1.1`) +3. Faça o commit das alterações e publique + +```bash +git commit -m "Update version to 0.1.1" +crewai tool publish +``` + +## Excluindo ferramentas + +Para excluir uma ferramenta: + +1. Acesse o [CrewAI Enterprise](https://app.crewai.com) +2. Navegue até **Ferramentas** +3. Selecione a ferramenta +4. Clique em **Excluir** + + +A exclusão é permanente. Ferramentas excluídas não podem ser restauradas ou reinstaladas. + + +## Verificações de segurança + +Cada versão publicada passa por verificações automáticas de segurança e só fica disponível para instalação após aprovação. + +Você pode verificar o status das verificações de segurança de uma ferramenta em: + +`CrewAI Enterprise > Tools > Your Tool > Versions` + + + + Entre em contato com nossa equipe de suporte para assistência com integração de API ou resolução de problemas. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/features/traces.mdx b/docs/pt-BR/enterprise/features/traces.mdx new file mode 100644 index 000000000..10d3dfae8 --- /dev/null +++ b/docs/pt-BR/enterprise/features/traces.mdx @@ -0,0 +1,146 @@ +--- +title: Traces +description: "Usando Traces para monitorar seus Crews" +icon: "timeline" +--- + +## Visão Geral + +Traces fornecem visibilidade abrangente sobre as execuções dos seus crews, ajudando você a monitorar o desempenho, depurar problemas e otimizar os fluxos de trabalho dos seus agentes de IA. + +## O que são Traces? + +Traces no CrewAI Enterprise são registros detalhados de execução que capturam todos os aspectos da operação do seu crew, desde as entradas iniciais até as saídas finais. Eles registram: + +- Pensamentos e raciocínio do agente +- Detalhes da execução das tarefas +- Uso de ferramentas e resultados +- Métricas de consumo de tokens +- Tempos de execução +- Estimativas de custo + + + ![Traces Overview](/images/enterprise/traces-overview.png) + + +## Acessando os Traces + + + + No seu painel do CrewAI Enterprise, clique em **Traces** para ver todos os registros de 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. + + + +## 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 + + + ![Execution Summary](/images/enterprise/trace-summary.png) + + +### 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 + + + ![Task List](/images/enterprise/trace-tasks.png) + + +### 3. Saída Final + +Exibe o resultado final produzido pelo crew após a conclusão de todas as tarefas. + + + ![Final Output](/images/enterprise/final-output.png) + + +### 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. + + + ![Execution Timeline](/images/enterprise/trace-timeline.png) + + +### 5. Visão Detalhada da Tarefa + +Ao clicar em uma tarefa específica na linha do tempo ou na lista de tarefas, você verá: + + + ![Detailed Task View](/images/enterprise/trace-detailed-task.png) + + +- **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: + + + + 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 + + + ![Failure Points](/images/enterprise/failure.png) + + + + + 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 + + + + 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 + + + + + Entre em contato com nossa equipe de suporte para assistência com análise de traces ou outros recursos do CrewAI Enterprise. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/features/webhook-streaming.mdx b/docs/pt-BR/enterprise/features/webhook-streaming.mdx new file mode 100644 index 000000000..ac4cbc5ee --- /dev/null +++ b/docs/pt-BR/enterprise/features/webhook-streaming.mdx @@ -0,0 +1,81 @@ +--- +title: Webhook Streaming +description: "Usando Webhook Streaming para transmitir eventos para o seu webhook" +icon: "webhook" +--- + +## Visão Geral + +O Enterprise Event Streaming permite que você receba atualizações em tempo real via webhook sobre suas crews e flows implantados no CrewAI Enterprise, como chamadas de modelo, uso de ferramentas e etapas do flow. + +## Uso + +Ao utilizar a API Kickoff, inclua um objeto `webhooks` em sua requisição, por exemplo: + +```json +{ + "inputs": {"foo": "bar"}, + "webhooks": { + "events": ["crew_kickoff_started", "llm_call_started"], + "url": "https://your.endpoint/webhook", + "realtime": false, + "authentication": { + "strategy": "bearer", + "token": "my-secret-token" + } + } +} +``` + +Se `realtime` estiver definido como `true`, cada evento será entregue individualmente e imediatamente, com impacto no desempenho da crew/flow. + +## Formato do Webhook + +Cada webhook envia uma lista de eventos: + +```json +{ + "events": [ + { + "id": "event-id", + "execution_id": "crew-run-id", + "timestamp": "2025-02-16T10:58:44.965Z", + "type": "llm_call_started", + "data": { + "model": "gpt-4", + "messages": [ + {"role": "system", "content": "You are an assistant."}, + {"role": "user", "content": "Summarize this article."} + ] + } + } + ] +} +``` + +A estrutura do objeto `data` varia conforme o tipo de evento. Consulte a [lista de eventos](https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events) no GitHub. + +Como as requisições são enviadas via HTTP, a ordem dos eventos não pode ser garantida. Caso precise de ordenação, utilize o campo `timestamp`. + +## Eventos Suportados + +O CrewAI oferece suporte a eventos do sistema e eventos personalizados no Enterprise Event Streaming. Esses eventos são enviados para o endpoint do seu webhook configurado durante a execução das crews e flows. + +- `crew_kickoff_started` +- `crew_step_started` +- `crew_step_completed` +- `crew_execution_completed` +- `llm_call_started` +- `llm_call_completed` +- `tool_usage_started` +- `tool_usage_completed` +- `crew_test_failed` +- *...e outros* + +Os nomes dos eventos correspondem ao event bus interno. Veja o [código fonte no GitHub](https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events) para a lista completa. + +Você pode emitir seus próprios eventos personalizados, e eles serão entregues através do webhook stream juntamente com os eventos do sistema. + + + Entre em contato com nossa equipe de suporte para assistência com integração de webhook ou solução de problemas. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/guides/azure-openai-setup.mdx b/docs/pt-BR/enterprise/guides/azure-openai-setup.mdx new file mode 100644 index 000000000..e2c022c45 --- /dev/null +++ b/docs/pt-BR/enterprise/guides/azure-openai-setup.mdx @@ -0,0 +1,51 @@ +--- +title: "Configuração do Azure OpenAI" +description: "Configure o Azure OpenAI com o Crew Studio para conexões empresariais de LLM" +icon: "microsoft" +--- + +Este guia orienta você na conexão do Azure OpenAI com o Crew Studio para operações de IA empresarial sem interrupções. + +## Processo de Configuração + + + + 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. + + Azure OpenAI Studio + + + + + 4. Em outra aba, abra `CrewAI Enterprise > LLM Connections`. Dê um nome à sua LLM Connection, selecione Azure como provedor e escolha o mesmo modelo que você selecionou no Azure. + 5. Na mesma página, adicione as variáveis de ambiente do passo 3: + - Uma chamada `AZURE_DEPLOYMENT_TARGET_URL` (usando o Target URI). A URL deve ser parecida com: https://your-deployment.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview + - Outra chamada `AZURE_API_KEY` (usando a Key). + 6. Clique em `Add Connection` para salvar sua LLM Connection. + + + + 7. Em `CrewAI Enterprise > Settings > Defaults > Crew Studio LLM Settings`, defina a nova LLM Connection e o modelo como padrão. + + + + 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. + + + +## 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 \ No newline at end of file diff --git a/docs/pt-BR/enterprise/guides/build-crew.mdx b/docs/pt-BR/enterprise/guides/build-crew.mdx new file mode 100644 index 000000000..531da7521 --- /dev/null +++ b/docs/pt-BR/enterprise/guides/build-crew.mdx @@ -0,0 +1,43 @@ +--- +title: "Build Crew" +description: "Uma Crew é um grupo de agentes que trabalham juntos para completar uma tarefa." +icon: "people-arrows" +--- + +## Visão Geral + +[CrewAI Enterprise](https://app.crewai.com) simplifica o processo de **criação**, **implantação** e **gerenciamento** dos seus agentes de IA em ambientes de produção. + +## Primeiros Passos + + + +### Instalação e Configuração + + + Siga nosso guia de instalação padrão para configurar o CrewAI CLI e criar seu primeiro projeto. + + +### Construindo Sua Crew + + + Siga nosso tutorial rápido para criar sua primeira crew de agentes usando a configuração YAML. + + +## 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). + + + + Reserve um horário com nossa equipe para saber mais sobre os recursos Enterprise e como eles podem beneficiar sua organização. + diff --git a/docs/pt-BR/enterprise/guides/deploy-crew.mdx b/docs/pt-BR/enterprise/guides/deploy-crew.mdx new file mode 100644 index 000000000..72c85441c --- /dev/null +++ b/docs/pt-BR/enterprise/guides/deploy-crew.mdx @@ -0,0 +1,293 @@ +--- +title: "Deploy Crew" +description: "Implantando um Crew na CrewAI Enterprise" +icon: "rocket" +--- + + +Depois de criar um crew localmente ou pelo Crew Studio, o próximo passo é implantá-lo na plataforma CrewAI Enterprise. Este guia cobre múltiplos métodos de implantação para ajudá-lo a escolher a melhor abordagem para o seu fluxo de trabalho. + + +## Pré-requisitos + + + + Você deve ter um crew funcional, criado localmente ou pelo Crew Studio + + + O código do seu crew deve estar em um repositório do GitHub (para o método de integração com GitHub) + + + +## Opção 1: Implantar Usando o CrewAI CLI + +A CLI fornece a maneira mais rápida de implantar crews desenvolvidos localmente na plataforma Enterprise. + + + + Se ainda não tiver, instale o CrewAI CLI: + + ```bash + pip install crewai[tools] + ``` + + + A CLI vem com o pacote principal CrewAI, mas o extra `[tools]` garante todas as dependências de implantação. + + + + + + Primeiro, você precisa autenticar sua CLI com a plataforma CrewAI Enterprise: + + ```bash + # Se já possui uma conta CrewAI Enterprise + crewai login + + # Se vai criar uma nova conta + crewai signup + ``` + + Ao executar qualquer um dos comandos, a CLI irá: + 1. Exibir uma URL e um código de dispositivo único + 2. Abrir seu navegador para a página de autenticação + 3. Solicitar a confirmação do dispositivo + 4. Completar o processo de autenticação + + Após a autenticação bem-sucedida, você verá uma mensagem de confirmação no terminal! + + + + + + 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 + ``` + + + + + + Acompanhe o status da implantação com: + + ```bash + crewai deploy status + ``` + + Para ver logs detalhados do processo de build: + + ```bash + crewai deploy logs + ``` + + + A primeira implantação normalmente leva de 10 a 15 minutos, pois as imagens dos containers são construídas. As próximas implantações são bem mais rápidas. + + + + + +## 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 + ``` + +## Opção 2: Implantar Diretamente pela Interface Web + +Você também pode implantar seus crews diretamente pela interface web da CrewAI Enterprise conectando sua conta do GitHub. Esta abordagem não requer utilizar a CLI na sua máquina local. + + + + + + Você precisa subir seu crew para um repositório do GitHub. Caso ainda não tenha criado um crew, você pode [seguir este tutorial](/pt-BR/quickstart). + + + + + + 1. Faça login em [CrewAI Enterprise](https://app.crewai.com) + 2. Clique no botão "Connect GitHub" + + + ![Botão Connect GitHub](/images/enterprise/connect-github.png) + + + + + + + Após conectar sua conta GitHub, você poderá selecionar qual repositório deseja implantar: + + + ![Selecionar Repositório](/images/enterprise/select-repo.png) + + + + + + + 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) + + + ![Definir Variáveis de Ambiente](/images/enterprise/set-env-variables.png) + + + + + + + 1. Clique no botão "Deploy" para iniciar o processo de implantação + 2. Você pode monitorar o progresso pela barra de progresso + 3. A primeira implantação geralmente demora de 10 a 15 minutos; as próximas serão mais rápidas + + + ![Progresso da Implantação](/images/enterprise/deploy-progress.png) + + + 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 + + + + + +## ⚠️ Requisitos de Segurança para Variáveis de Ambiente + + +**Importante**: A CrewAI Enterprise possui restrições de segurança sobre os nomes de variáveis de ambiente que podem causar falha na implantação caso não sejam seguidas. + + +### Padrões de Variáveis de Ambiente Bloqueados + +Por motivos de segurança, os seguintes padrões de nome de variável de ambiente são **automaticamente filtrados** e causarão problemas de implantação: + +**Padrões Bloqueados:** +- Variáveis terminando em `_TOKEN` (ex: `MY_API_TOKEN`) +- Variáveis terminando em `_PASSWORD` (ex: `DB_PASSWORD`) +- Variáveis terminando em `_SECRET` (ex: `API_SECRET`) +- Variáveis terminando em `_KEY` em certos contextos + +**Variáveis Bloqueadas Específicas:** +- `GITHUB_USER`, `GITHUB_TOKEN` +- `AWS_REGION`, `AWS_DEFAULT_REGION` +- Diversas variáveis internas do sistema CrewAI + +### Exceções Permitidas + +Algumas variáveis são explicitamente permitidas mesmo coincidindo com os padrões bloqueados: +- `AZURE_AD_TOKEN` +- `AZURE_OPENAI_AD_TOKEN` +- `ENTERPRISE_ACTION_TOKEN` +- `CREWAI_ENTEPRISE_TOOLS_TOKEN` + +### Como Corrigir Problemas de Nomeação + +Se sua implantação falhar devido a restrições de variáveis de ambiente: + +```bash +# ❌ Estas irão causar falhas na implantação +OPENAI_TOKEN=sk-... +DATABASE_PASSWORD=mysenha +API_SECRET=segredo123 + +# ✅ Utilize estes padrões de nomeação +OPENAI_API_KEY=sk-... +DATABASE_CREDENTIALS=mysenha +API_CONFIG=segredo123 +``` + +### Melhores Práticas + +1. **Use convenções padrão de nomenclatura**: `PROVIDER_API_KEY` em vez de `PROVIDER_TOKEN` +2. **Teste localmente primeiro**: Certifique-se de que seu crew funciona com as variáveis renomeadas +3. **Atualize seu código**: Altere todas as referências aos nomes antigos das variáveis +4. **Documente as mudanças**: Mantenha registro das variáveis renomeadas para seu time + + +Se você se deparar com falhas de implantação com erros enigmáticos de variáveis de ambiente, confira primeiro os nomes das variáveis em relação a esses padrões. + + +### Interaja com Seu Crew Implantado + +Após a implantação, você pode acessar seu crew por meio de: + +1. **REST API**: A plataforma gera um endpoint HTTPS exclusivo com estas rotas principais: + - `/inputs`: Lista os parâmetros de entrada requeridos + - `/kickoff`: Inicia uma execução com os inputs fornecidos + - `/status/{kickoff_id}`: Consulta o status da execução + +2. **Interface Web**: Acesse [app.crewai.com](https://app.crewai.com) para visualizar: + - **Aba Status**: Informações da implantação, detalhes do endpoint da API e token de autenticação + - **Aba Run**: Visualização da estrutura do seu crew + - **Aba Executions**: Histórico de todas as execuções + - **Aba Metrics**: Análises de desempenho + - **Aba Traces**: Insights detalhados das execuções + +### Dispare uma Execução + +No dashboard Enterprise, você pode: + +1. Clicar no nome do seu crew para abrir seus detalhes +2. Selecionar "Trigger Crew" na interface de gerenciamento +3. Inserir os inputs necessários no modal exibido +4. Monitorar o progresso à medida que a execução avança pelo pipeline + +### Monitoramento e Análises + +A plataforma Enterprise oferece recursos abrangentes de observabilidade: + +- **Gestão das Execuções**: Acompanhe execuções ativas e concluídas +- **Traces**: Quebra detalhada de cada execução +- **Métricas**: Uso de tokens, tempos de execução e custos +- **Visualização em Linha do Tempo**: Representação visual das sequências de tarefas + +### Funcionalidades Avançadas + +A plataforma Enterprise também oferece: + +- **Gerenciamento de Variáveis de Ambiente**: Armazene e gerencie com segurança as chaves de API +- **Conexões com LLM**: Configure integrações com diversos provedores de LLM +- **Repositório Custom Tools**: Crie, compartilhe e instale ferramentas +- **Crew Studio**: Monte crews via interface de chat sem escrever código + + + Entre em contato com nossa equipe de suporte para ajuda com questões de implantação ou dúvidas sobre a plataforma Enterprise. + diff --git a/docs/pt-BR/enterprise/guides/enable-crew-studio.mdx b/docs/pt-BR/enterprise/guides/enable-crew-studio.mdx new file mode 100644 index 000000000..62adb44fb --- /dev/null +++ b/docs/pt-BR/enterprise/guides/enable-crew-studio.mdx @@ -0,0 +1,165 @@ +--- +title: "Ativar Crew Studio" +description: "Ativando o Crew Studio no CrewAI Enterprise" +icon: "comments" +--- + + +Crew Studio é uma poderosa ferramenta **no-code/low-code** que permite criar ou estruturar Crews rapidamente por meio de uma interface conversacional. + + +## O que é o Crew Studio? + +O Crew Studio é uma forma inovadora de criar equipes de agentes de IA sem escrever código. + + + ![Crew Studio Interface](/images/enterprise/crew-studio-interface.png) + + +Com o Crew Studio, você pode: + +- Conversar com o Crew Assistant para descrever seu problema +- Gerar automaticamente agentes e tarefas +- Selecionar as ferramentas apropriadas +- Configurar os inputs necessários +- Gerar código para download e personalização +- Fazer deploy diretamente na plataforma CrewAI Enterprise + +## Etapas de Configuração + +Antes de começar a usar o Crew Studio, você precisa configurar suas conexões LLM: + + + + Acesse a aba **LLM Connections** no painel do CrewAI Enterprise e crie uma nova conexão LLM. + + + Sinta-se à vontade para utilizar qualquer provedor LLM suportado pelo CrewAI. + + + 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 + + + ![LLM Connection Configuration](/images/enterprise/llm-connection-config.png) + + + + + Assim que concluir a configuração, você verá sua nova conexão adicionada à lista de conexões disponíveis. + + + ![Connection Added](/images/enterprise/connection-added.png) + + + + + 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. + + + ![LLM Defaults Configuration](/images/enterprise/llm-defaults.png) + + + + +## 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! + + + + Navegue até a seção **Studio** no painel do CrewAI Enterprise. + + + + 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. + + + + 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. + + + + Quando estiver satisfeito com a configuração, você pode: + + - Baixar o código gerado para personalização local + - Fazer deploy do crew diretamente na plataforma CrewAI Enterprise + - Modificar a configuração e gerar o crew novamente + + + + Após o deploy, teste seu crew com inputs de exemplo para garantir que ele funcione conforme esperado. + + + + +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. + + +## Exemplo de Fluxo de Trabalho + +Veja um fluxo de trabalho típico para criação de um crew com o Crew Studio: + + + + Comece descrevendo seu problema: + + ```md + I need a crew that can analyze financial news and provide investment recommendations + ``` + + + + Responda às perguntas de esclarecimento do Crew Assistant para refinar seus requisitos. + + + + 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 + + + + Aprove o plano ou solicite alterações, se necessário. + + + + Baixe o código para personalização ou faça o deploy diretamente na plataforma. + + + + Teste seu crew com inputs de exemplo e faça ajustes conforme necessário. + + + + + Entre em contato com nossa equipe de suporte para obter assistência com o Crew Studio ou qualquer outro recurso do CrewAI Enterprise. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/guides/hubspot-trigger.mdx b/docs/pt-BR/enterprise/guides/hubspot-trigger.mdx new file mode 100644 index 000000000..95c00ecfd --- /dev/null +++ b/docs/pt-BR/enterprise/guides/hubspot-trigger.mdx @@ -0,0 +1,53 @@ +--- +title: "Gatilho HubSpot" +description: "Acione crews do CrewAI diretamente a partir de Workflows do HubSpot" +icon: "hubspot" +--- + +Este guia fornece um processo passo a passo para configurar gatilhos do HubSpot para o CrewAI Enterprise, permitindo iniciar crews diretamente a partir de Workflows do HubSpot. + +## Pré-requisitos + +- Uma conta CrewAI Enterprise +- Uma conta HubSpot com o recurso de [Workflows do HubSpot](https://knowledge.hubspot.com/workflows/create-workflows) + +## Etapas de Configuração + + + + - Faça login na sua `Conta CrewAI Enterprise > Triggers` + - Selecione `HubSpot` na lista de gatilhos disponíveis + - Escolha a conta HubSpot que deseja conectar ao CrewAI Enterprise + - Siga as instruções na tela para autorizar o acesso do CrewAI Enterprise à sua conta HubSpot + - Uma mensagem de confirmação aparecerá assim que o HubSpot estiver conectado com sucesso ao CrewAI Enterprise + + + - 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 + + HubSpot Workflow 1 + + + + - 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 + + HubSpot Workflow 2 + + - Configure quaisquer ações adicionais necessárias + - Revise as etapas do seu workflow para garantir que tudo está configurado corretamente + - Ative o workflow + + HubSpot Workflow 3 + + + + +## 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). \ No newline at end of file diff --git a/docs/pt-BR/enterprise/guides/human-in-the-loop.mdx b/docs/pt-BR/enterprise/guides/human-in-the-loop.mdx new file mode 100644 index 000000000..f946948eb --- /dev/null +++ b/docs/pt-BR/enterprise/guides/human-in-the-loop.mdx @@ -0,0 +1,78 @@ +--- +title: "Workflows HITL" +description: "Aprenda como implementar workflows Human-In-The-Loop no CrewAI para decisões aprimoradas" +icon: "user-check" +--- + +Human-In-The-Loop (HITL) é uma abordagem poderosa que combina inteligência artificial com expertise humana para aprimorar a tomada de decisão e melhorar os resultados das tarefas. Este guia mostra como implementar HITL dentro do CrewAI. + +## Configurando Workflows HITL + + + + Configure sua tarefa com a entrada humana habilitada: + + Crew Human Input + + + + + Ao iniciar seu crew, inclua um URL de webhook para entrada humana: + + Crew Webhook URL + + + + + 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** + + + + O sistema irá pausar no estado `Pending Human Input`. Revise cuidadosamente a saída da tarefa. + + + + Chame o endpoint de retomada do seu crew com as seguintes informações: + + Crew Resume Endpoint + + + **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. + + 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. + + + 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. + + + + Quando você enviar um feedback positivo, a execução prosseguirá para as próximas etapas. + + + +## 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 \ No newline at end of file diff --git a/docs/pt-BR/enterprise/guides/kickoff-crew.mdx b/docs/pt-BR/enterprise/guides/kickoff-crew.mdx new file mode 100644 index 000000000..a43a41f45 --- /dev/null +++ b/docs/pt-BR/enterprise/guides/kickoff-crew.mdx @@ -0,0 +1,185 @@ +--- +title: "Kickoff Crew" +description: "Inicie um Crew no CrewAI Enterprise" +icon: "flag-checkered" +--- + +## Visão Geral + +Uma vez que você tenha implantado seu crew na plataforma CrewAI Enterprise, é possível iniciar execuções pela interface web ou pela API. Este guia aborda ambos os métodos. + +## Método 1: Usando a Interface Web + +### Passo 1: Navegue até seu Crew Implantado + +1. Faça login no [CrewAI Enterprise](https://app.crewai.com) +2. Clique no nome do crew na sua lista de projetos +3. Você será direcionado para a página de detalhes do crew + + + ![Crew Dashboard](/images/enterprise/crew-dashboard.png) + + +### 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` + + + ![Kickoff Endpoint](/images/enterprise/kickoff-endpoint.png) + + +#### 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` + + + ![Run Crew](/images/enterprise/run-crew.png) + + +### 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 + + + ![Copy Task ID](/images/enterprise/copy-task-id.png) + + +### 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" + + + ![Get Status](/images/enterprise/get-status.png) + + +A resposta de status mostrará: +- Estado atual da execução (`running`, `completed`, etc.) +- Detalhes sobre quais tarefas estão em andamento +- Quaisquer outputs gerados até o momento + +### Passo 5: Visualizar Resultados Finais + +Quando a execução for concluída: + +1. O status mudará para `completed` +2. Você poderá visualizar todos os resultados e outputs da execução +3. Para uma visão mais detalhada, acesse a aba `Executions` na página de detalhes do crew + +## Método 2: Usando a API + +Você também pode iniciar crews programaticamente usando a REST API do CrewAI Enterprise. + +### Autenticação + +Todas as requisições à API exigem um bearer token para autenticação: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com +``` + +Seu bearer token está disponível na aba Status na página de detalhes do seu crew. + +### Verificando o Status do Crew + +Antes de executar operações, você pode verificar se seu crew está funcionando corretamente: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com +``` + +Uma resposta de sucesso trará uma mensagem indicando que o crew está operacional: + +``` +Healthy% +``` + +### Passo 1: Recuperar Entradas Necessárias + +Primeiro, descubra quais entradas seu crew exige: + +```bash +curl -X GET \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/inputs +``` + +A resposta será um objeto JSON contendo um array de parâmetros de entrada obrigatórios, por exemplo: + +```json +{"inputs":["topic","current_year"]} +``` + +Este exemplo mostra que este crew em particular requer dois inputs: `topic` e `current_year`. + +### Passo 2: Iniciar Execução + +Inicie a execução fornecendo os inputs obrigatórios: + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + -d '{"inputs": {"topic": "AI Agent Frameworks", "current_year": "2025"}}' \ + https://your-crew-url.crewai.com/kickoff +``` + +A resposta incluirá um `kickoff_id` que você precisará para o acompanhamento: + +```json +{"kickoff_id":"abcd1234-5678-90ef-ghij-klmnopqrstuv"} +``` + +### Passo 3: Verificar Status da Execução + +Acompanhe o progresso da execução usando o kickoff_id: + +```bash +curl -X GET \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv +``` + +## Gerenciando Execuções + +### Execuções de Longa Duração + +Para execuções que possam demandar mais tempo: + +1. Considere implementar um mecanismo de polling para verificar status periodicamente +2. Utilize webhooks (se disponíveis) para notificação quando a execução for concluída +3. Implemente tratamento de erros para possíveis timeouts + +### Contexto da Execução + +O contexto da execução inclui: + +- Inputs fornecidos no momento do kickoff +- Variáveis de ambiente configuradas durante o deploy +- Qualquer estado mantido entre as tarefas + +### Depuração de Execuções com Falha + +Se uma execução falhar: + +1. Verifique a aba "Executions" para logs detalhados +2. Avalie a aba "Traces" para detalhes passo a passo da execução +3. Procure por respostas LLM e uso de ferramentas nos detalhes do trace + + + Entre em contato com nossa equipe de suporte para obter ajuda com problemas de execução ou dúvidas sobre a plataforma Enterprise. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/guides/react-component-export.mdx b/docs/pt-BR/enterprise/guides/react-component-export.mdx new file mode 100644 index 000000000..decc90b6f --- /dev/null +++ b/docs/pt-BR/enterprise/guides/react-component-export.mdx @@ -0,0 +1,103 @@ +--- +title: "Exportação de Componentes React" +description: "Aprenda como exportar e integrar componentes React do CrewAI Enterprise em suas aplicações" +icon: "react" +--- + +Este guia explica como exportar crews do CrewAI Enterprise como componentes React e integrá-los às suas próprias aplicações. + +## Exportando um Componente React + + + + 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. + + + Exportar Componente React + + + + +## 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. + + + + - Baixe e instale o Node.js no site oficial: https://nodejs.org/ + - Escolha a versão LTS (Long Term Support) para maior estabilidade. + + + + - 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 + ``` + + + + ```bash + npm install react-dom + ``` + + + + - Mova o arquivo baixado `CrewLead.jsx` para a pasta `src` do seu projeto. + + + + - 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 ( +
+ +
+ ); + } + + export default App; + ``` + - Substitua `YOUR_API_BASE_URL` e `YOUR_BEARER_TOKEN` pelos valores reais da sua API. +
+ + + - 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. + +
+ +## Personalização + +Você pode então personalizar o `CrewLead.jsx` para adicionar cor, título etc. + + + Personalizar Componente React + + + Personalizar Componente React + + +## 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 \ No newline at end of file diff --git a/docs/pt-BR/enterprise/guides/salesforce-trigger.mdx b/docs/pt-BR/enterprise/guides/salesforce-trigger.mdx new file mode 100644 index 000000000..9b44f624a --- /dev/null +++ b/docs/pt-BR/enterprise/guides/salesforce-trigger.mdx @@ -0,0 +1,44 @@ +--- +title: "Trigger Salesforce" +description: "Dispare equipes CrewAI a partir de fluxos de trabalho do Salesforce para automação de CRM" +icon: "salesforce" +--- + +A CrewAI Enterprise pode ser acionada a partir do Salesforce para automatizar fluxos de trabalho de gestão de relacionamento com o cliente e aprimorar suas operações de vendas. + +## Visão Geral + +O Salesforce é uma das principais plataformas de gestão de relacionamento com o cliente (CRM), que ajuda empresas a otimizar operações de vendas, atendimento e marketing. Ao configurar triggers da CrewAI a partir do Salesforce, você pode: + +- Automatizar a classificação e qualificação de leads +- Gerar materiais de vendas personalizados +- Aprimorar o atendimento ao cliente com respostas baseadas em IA +- Otimizar análise e relatórios de dados + +## Demonstração + + + + + +## Primeiros Passos + +Para configurar triggers no Salesforce: + +1. **Contato com o Suporte**: Entre em contato com o suporte da CrewAI Enterprise para obter assistência na configuração dos triggers no Salesforce +2. **Revisar Requisitos**: Certifique-se de possuir as permissões necessárias no Salesforce e acesso à API +3. **Configurar Conexão**: Trabalhe com a equipe de suporte para estabelecer a conexão entre a CrewAI e sua instância do Salesforce +4. **Testar Triggers**: Verifique se os triggers funcionam corretamente para os seus casos de uso específicos + +## Casos de Uso + +Cenários comuns de uso de triggers Salesforce + CrewAI incluem: + +- **Processamento de Leads**: Analisar e classificar leads recebidos automaticamente +- **Geração de Propostas**: Criar propostas personalizadas com base nos dados das oportunidades +- **Insights de Clientes**: Gerar relatórios de análise a partir do histórico de interações com clientes +- **Automação de Follow-up**: Criar mensagens de follow-up e recomendações personalizadas + +## Próximos Passos + +Para instruções detalhadas de configuração e opções avançadas, entre em contato com o suporte da CrewAI Enterprise, que pode fornecer orientações personalizadas para o seu ambiente Salesforce e necessidades de negócio. \ No newline at end of file diff --git a/docs/pt-BR/enterprise/guides/slack-trigger.mdx b/docs/pt-BR/enterprise/guides/slack-trigger.mdx new file mode 100644 index 000000000..fc916888c --- /dev/null +++ b/docs/pt-BR/enterprise/guides/slack-trigger.mdx @@ -0,0 +1,61 @@ +--- +title: "Slack Trigger" +description: "Acione crews do CrewAI diretamente do Slack usando comandos de barra" +icon: "slack" +--- + +Este guia explica como iniciar um crew diretamente do Slack usando triggers do CrewAI. + +## Pré-requisitos + +- Trigger do CrewAI para Slack instalado e conectado ao seu workspace do Slack +- Pelo menos um crew configurado no CrewAI + +## Etapas de Configuração + + + + No dashboard do CrewAI, navegue até a seção **Triggers**. + + + Integração CrewAI Slack + + + Verifique se o Slack está listado e conectado. + + + - 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: + + Kickoff crew + + - Pressione Enter ou selecione a opção "**Kickoff crew**". Uma caixa de diálogo intitulada "**Kickoff an AI Crew**" aparecerá. + + + - No menu suspenso rotulado "**Select of the crews online:**", escolha o crew que deseja iniciar. + - No exemplo abaixo, "**prep-for-meeting**" está selecionado: + + Kickoff crew dropdown + + - Se o seu crew exigir algum input, clique no botão "**Add Inputs**" para fornecê-los. + + O botão "**Add Inputs**" é mostrado no exemplo acima, mas ainda não foi clicado. + + + + - Assim que você tiver selecionado o crew e adicionado os inputs necessários, clique em "**Kickoff**" para iniciar o crew. + + Kickoff crew + + - O crew começará a ser executado e você verá os resultados no canal do Slack. + + Kickoff crew results + + + + +## 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. \ No newline at end of file diff --git a/docs/pt-BR/enterprise/guides/team-management.mdx b/docs/pt-BR/enterprise/guides/team-management.mdx new file mode 100644 index 000000000..5ceadbafd --- /dev/null +++ b/docs/pt-BR/enterprise/guides/team-management.mdx @@ -0,0 +1,87 @@ +--- +title: "Gestão de Equipes" +description: "Aprenda como convidar e gerenciar membros da equipe em sua organização CrewAI Enterprise" +icon: "users" +--- + +Como administrador de uma conta CrewAI Enterprise, você pode facilmente convidar novos membros para sua organização. Este guia irá orientá-lo passo a passo pelo processo. + +## Convidando Membros da Equipe + + + + - Faça login na sua conta CrewAI Enterprise + - Procure o ícone de engrenagem (⚙️) no canto superior direito do painel + - Clique no ícone de engrenagem para acessar a página de **Configurações**: + + Página de Configurações + + + + - Na página de Configurações, você verá a aba `Members` + - Clique na aba `Members` para acessar a página de **Membros**: + + Aba 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 + + + - 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 + + + +## Adicionando Funções + +Você pode adicionar funções aos membros da equipe para controlar o acesso a diferentes partes da plataforma. + + + + - Faça login na sua conta CrewAI Enterprise + - Procure o ícone de engrenagem (⚙️) no canto superior direito do painel + - Clique no ícone de engrenagem para acessar a página de **Configurações**: + + Página de Configurações + + + + - Na página de Configurações, você verá a aba `Roles` + - Clique na aba `Roles` para acessar a página de **Funções**. + + Aba Funções + + - 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. + + Modal Adicionar Função + + + + - Na seção de Membros, você verá uma lista dos membros atuais (incluindo você) + + Membro Aceitou Convite + + - 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 + + Adicionar Função ao Membro + + + + +## Notas Importantes + +- **Privilégios de Administrador**: Apenas usuários com privilégios administrativos podem convidar novos membros +- **Precisão do E-mail**: Certifique-se de que você tem os endereços de e-mail corretos dos membros da equipe +- **Aceite do Convite**: Os membros convidados precisarão aceitar o convite para ingressar na sua organização +- **Notificações por E-mail**: Oriente seus membros a verificarem o e-mail (incluindo a pasta de spam) para localizar o convite + +Seguindo estes passos, você conseguirá expandir sua equipe e colaborar de forma mais eficaz dentro da sua organização CrewAI Enterprise. \ No newline at end of file diff --git a/docs/pt-BR/enterprise/guides/update-crew.mdx b/docs/pt-BR/enterprise/guides/update-crew.mdx new file mode 100644 index 000000000..1c377107c --- /dev/null +++ b/docs/pt-BR/enterprise/guides/update-crew.mdx @@ -0,0 +1,88 @@ +--- +title: "Atualizar Crew" +description: "Atualizando uma Crew no CrewAI Enterprise" +icon: "pencil" +--- + + +Após implantar sua crew no CrewAI Enterprise, pode ser necessário fazer atualizações no código, configurações de segurança ou configuração. +Este guia explica como realizar essas operações de atualização comuns. + + +## Por que atualizar sua Crew? + +Por padrão, o CrewAI não irá buscar atualizações do GitHub automaticamente, então você precisará acionar manualmente as atualizações, a menos que tenha marcado a opção `Auto-update` ao implantar sua crew. + +Há várias razões para querer atualizar sua implantação de crew: +- Você deseja atualizar o código com o commit mais recente que enviou para o GitHub +- Você deseja redefinir o bearer token por motivos de segurança +- Você deseja atualizar variáveis de ambiente + +## 1. Atualizando o código da sua Crew para o último commit + +Quando você fizer push de novos commits no seu repositório do GitHub e quiser atualizar sua implantação: + +1. Navegue até sua crew na plataforma CrewAI Enterprise +2. Clique no botão `Re-deploy` na página de detalhes da sua crew + + + ![Botão Re-deploy](/images/enterprise/redeploy-button.png) + + +Isso irá acionar uma atualização que pode ser acompanhada pela barra de progresso. O sistema irá buscar o código mais recente do seu repositório e reconstruir sua implantação. + +## 2. Redefinindo o Bearer Token + +Se precisar gerar um novo bearer token (por exemplo, se suspeitar que o token atual possa ter sido comprometido): + +1. Navegue até sua crew na plataforma CrewAI Enterprise +2. Encontre a seção `Bearer Token` +3. Clique no botão `Reset` ao lado do token atual + + + ![Reset Token](/images/enterprise/reset-token.png) + + + +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. + + +## 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 + + + ![Botão Variáveis de Ambiente](/images/enterprise/env-vars-button.png) + + +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 + + + ![Atualizar Variáveis de Ambiente](/images/enterprise/update-env-vars.png) + + +5. Por fim, clique no botão `Update Deployment` na parte inferior da página para aplicar as alterações + + +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. + + +## 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 + + +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. + + + + 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. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/guides/webhook-automation.mdx b/docs/pt-BR/enterprise/guides/webhook-automation.mdx new file mode 100644 index 000000000..1f90185e4 --- /dev/null +++ b/docs/pt-BR/enterprise/guides/webhook-automation.mdx @@ -0,0 +1,121 @@ +--- +title: "Automação com Webhook" +description: "Automatize fluxos de trabalho do CrewAI Enterprise usando webhooks com plataformas como ActivePieces, Zapier e Make.com" +icon: "webhook" +--- + +O CrewAI Enterprise permite que você automatize seu fluxo de trabalho usando webhooks. Este artigo irá guiá-lo no processo de configuração e uso de webhooks para iniciar a execução do crew, com foco na integração com o ActivePieces, uma plataforma de automação de fluxos de trabalho semelhante ao Zapier e Make.com. + +## Configurando Webhooks + + + + - Navegue até o painel do CrewAI Enterprise + - Procure pela seção `/kickoff`, que é usada para iniciar a execução do crew + + Interface Kickoff + + + + + 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) + + + + 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`) + + Gatilho ActivePieces + + + 3. Adicione uma etapa de ação HTTP + - Configure a ação como `Send HTTP request` + - Use o método `POST` + - Defina a URL para o endpoint de kickoff do CrewAI Enterprise + - Adicione os headers necessários (ex.: `Bearer Token`) + + Headers ActivePieces + + + - No corpo, inclua o conteúdo JSON conforme configurado na etapa 2 + + Body ActivePieces + + + - O crew será iniciado no horário pré-definido. + + + + 1. Crie um novo flow no ActivePieces e nomeie-o + + Flow ActivePieces + + + 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 + + Webhook ActivePieces + + + - Configure o e-mail para usar o corpo de texto do webhook do crew + + Email ActivePieces + + + + +## Exemplos de Output do 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" + } + ``` + + + `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" + } + ``` + + + `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." + ] + } + } + ``` + + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/guides/zapier-trigger.mdx b/docs/pt-BR/enterprise/guides/zapier-trigger.mdx new file mode 100644 index 000000000..a6796d21e --- /dev/null +++ b/docs/pt-BR/enterprise/guides/zapier-trigger.mdx @@ -0,0 +1,103 @@ +--- +title: "Trigger Zapier" +description: "Dispare crews do CrewAI a partir de fluxos de trabalho no Zapier para automatizar fluxos multiaplicativos" +icon: "bolt" +--- + +Este guia irá conduzi-lo pelo processo de configuração de triggers no Zapier para o CrewAI Enterprise, permitindo automatizar fluxos de trabalho entre CrewAI Enterprise e outros aplicativos. + +## Pré-requisitos + +- Uma conta CrewAI Enterprise +- Uma conta Zapier +- Uma conta Slack (para este exemplo específico) + +## Configuração Passo a Passo + + + + - No Zapier, crie um novo Zap. + + + Zapier 1 + + + + + + Zapier 2 + + - Selecione `New Pushed Message` como o Evento de Trigger. + - Conecte sua conta Slack, caso ainda não tenha feito isso. + + + + - 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. + + + Zapier 5 + + + + + - Conecte sua conta CrewAI Enterprise. + - Selecione o Crew apropriado para seu fluxo de trabalho. + + + Zapier 6 + + - Configure as entradas para o Crew usando os dados da mensagem do Slack. + + + + - Adicione outra etapa de ação para formatar a saída de texto do CrewAI Enterprise. + - Utilize as ferramentas de formatação do Zapier para converter a saída em Markdown para HTML. + + + Zapier 8 + + + Zapier 9 + + + + + - Adicione uma etapa final de ação para enviar a saída formatada por e-mail. + - Escolha seu serviço de e-mail preferido (ex.: Gmail, Outlook). + - Configure os detalhes do e-mail, incluindo destinatário, assunto e corpo. + - Insira a saída formatada do CrewAI Enterprise no corpo do e-mail. + + + Zapier 7 + + + + + - Digite o texto no seu canal do Slack + + + Zapier 10 + + + - Selecione o botão de três pontos e então escolha Push to Zapier + + + Zapier 11 + + + + + + Zapier 12 + + + + +## Dicas para o Sucesso + +- Certifique-se de que as entradas do CrewAI Enterprise estejam corretamente mapeadas a partir da mensagem do Slack. +- Teste seu Zap cuidadosamente antes de ativá-lo para identificar possíveis problemas. +- Considere adicionar etapas de tratamento de erros para gerenciar possíveis falhas no fluxo. + +Seguindo estes passos, você terá configurado com sucesso triggers no Zapier para o CrewAI Enterprise, permitindo fluxos de trabalho automatizados disparados por mensagens no Slack e resultando em notificações por e-mail com a saída do CrewAI Enterprise. \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/asana.mdx b/docs/pt-BR/enterprise/integrations/asana.mdx new file mode 100644 index 000000000..c926aed08 --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/asana.mdx @@ -0,0 +1,253 @@ +--- +title: Integração com Asana +description: "Coordenação de tarefas e projetos em equipe com a integração Asana para CrewAI." +icon: "circle" +--- + +## Visão Geral + +Permita que seus agentes gerenciem tarefas, projetos e a coordenação da equipe através do Asana. Crie tarefas, atualize o status de projetos, gerencie atribuições e otimize o fluxo de trabalho da sua equipe com automação baseada em IA. + +## Pré-requisitos + +Antes de usar a integração com o Asana, assegure-se de ter: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa +- Uma conta Asana com as permissões apropriadas +- Sua conta Asana conectada através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração Asana + +### 1. Conecte sua Conta Asana + +1. Acesse [CrewAI Enterprise Integrações](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Asana** na seção Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para gerenciamento de tarefas e projetos +5. Copie seu Token Enterprise em [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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."). + + + + **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."). + + + + **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` + + + + **Descrição:** Obtém um projeto pelo ID no Asana. + + **Parâmetros:** + - `projectFilterId` (string, obrigatório): ID do Projeto. + + + + **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. + + + + **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. + + + + **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"). + + + + **Descrição:** Obtém uma lista de tarefas pelo ID no Asana. + + **Parâmetros:** + - `taskId` (string, obrigatório): ID da Tarefa. + + + + **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. + + + + **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"). + + + + **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. + + + + **Descrição:** Obtém uma lista de áreas de trabalho do Asana. + + **Parâmetros:** Nenhum obrigatório. + + + +## Exemplos de Uso + +### Configuração Básica do Agente Asana + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Get enterprise tools (Asana tools will be included) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Create an agent with Asana capabilities +asana_agent = Agent( + role="Project Manager", + goal="Manage tasks and projects in Asana efficiently", + backstory="An AI assistant specialized in project management and task coordination.", + tools=[enterprise_tools] +) + +# Task to create a new project +create_project_task = Task( + description="Create a new project called 'Q1 Marketing Campaign' in the Marketing workspace", + agent=asana_agent, + expected_output="Confirmation that the project was created successfully with project ID" +) + +# Run the task +crew = Crew( + agents=[asana_agent], + tasks=[create_project_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Asana + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Get only specific Asana tools +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["asana_create_task", "asana_update_task", "asana_get_tasks"] +) + +task_manager_agent = Agent( + role="Task Manager", + goal="Create and manage tasks efficiently", + backstory="An AI assistant that focuses on task creation and management.", + tools=enterprise_tools +) + +# Task to create and assign a task +task_management = Task( + description="Create a task called 'Review quarterly reports' and assign it to the appropriate team member", + agent=task_manager_agent, + expected_output="Task created and assigned successfully" +) + +crew = Crew( + agents=[task_manager_agent], + tasks=[task_management] +) + +crew.kickoff() +``` + +### Gerenciamento Avançado de Projetos + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +project_coordinator = Agent( + role="Project Coordinator", + goal="Coordinate project activities and track progress", + backstory="An experienced project coordinator who ensures projects run smoothly.", + tools=[enterprise_tools] +) + +# Complex task involving multiple Asana operations +coordination_task = Task( + description=""" + 1. Get all active projects in the workspace + 2. For each project, get the list of incomplete tasks + 3. Create a summary report task in the 'Management Reports' project + 4. Add comments to overdue tasks to request status updates + """, + agent=project_coordinator, + expected_output="Summary report created and status update requests sent for overdue tasks" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[coordination_task] +) + +crew.kickoff() +``` \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/box.mdx b/docs/pt-BR/enterprise/integrations/box.mdx new file mode 100644 index 000000000..ad26dbf5c --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/box.mdx @@ -0,0 +1,268 @@ +--- +title: Integração com Box +description: "Armazenamento de arquivos e gerenciamento de documentos com a integração do Box para CrewAI." +icon: "box" +--- + +## Visão Geral + +Permita que seus agentes gerenciem arquivos, pastas e documentos através do Box. Faça upload de arquivos, organize estruturas de pastas, pesquise conteúdos e otimize o gerenciamento de documentos da sua equipe com automação alimentada por IA. + +## Pré-requisitos + +Antes de utilizar a integração com o Box, assegure-se de que você possui: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa +- Uma conta Box com as permissões apropriadas +- Sua conta Box conectada através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com o Box + +### 1. Conecte sua conta Box + +1. Acesse [Integrações do CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Box** na seção de Integrações de Autenticação +3. Clique em **Conectar** e conclua o fluxo de OAuth +4. Conceda as permissões necessárias para gerenciamento de arquivos e pastas +5. Copie seu Token Enterprise em [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account) + +### 2. Instale o pacote necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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"). + + + + **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. + + + + **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"). + + + + **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" + } + ] + } + ] + } + ``` + + + + **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" + } + ``` + + + + **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" + } + ``` + + + + **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"). + + + + **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" + } + ] + } + ] + } + ``` + + + + **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. + + + +## Exemplos de Uso + +### Configuração Básica de Agente Box + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Get enterprise tools (Box tools will be included) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Create an agent with Box capabilities +box_agent = Agent( + role="Document Manager", + goal="Manage files and folders in Box efficiently", + backstory="An AI assistant specialized in document management and file organization.", + tools=[enterprise_tools] +) + +# Task to create a folder structure +create_structure_task = Task( + description="Create a folder called 'Project Files' in the root directory and upload a document from URL", + agent=box_agent, + expected_output="Folder created and file uploaded successfully" +) + +# Run the task +crew = Crew( + agents=[box_agent], + tasks=[create_structure_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Box + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Get only specific Box tools +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["box_create_folder", "box_save_file", "box_list_files"] +) + +file_organizer_agent = Agent( + role="File Organizer", + goal="Organize and manage file storage efficiently", + backstory="An AI assistant that focuses on file organization and storage management.", + tools=enterprise_tools +) + +# Task to organize files +organization_task = Task( + description="Create a folder structure for the marketing team and organize existing files", + agent=file_organizer_agent, + expected_output="Folder structure created and files organized" +) + +crew = Crew( + agents=[file_organizer_agent], + tasks=[organization_task] +) + +crew.kickoff() +``` + +### Gerenciamento Avançado de Arquivos + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +file_manager = Agent( + role="File Manager", + goal="Maintain organized file structure and manage document lifecycle", + backstory="An experienced file manager who ensures documents are properly organized and accessible.", + tools=[enterprise_tools] +) + +# Complex task involving multiple Box operations +management_task = Task( + description=""" + 1. List all files in the root folder + 2. Create monthly archive folders for the current year + 3. Move old files to appropriate archive folders + 4. Generate a summary report of the file organization + """, + agent=file_manager, + expected_output="Files organized into archive structure with summary report" +) + +crew = Crew( + agents=[file_manager], + tasks=[management_task] +) + +crew.kickoff() +``` \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/clickup.mdx b/docs/pt-BR/enterprise/integrations/clickup.mdx new file mode 100644 index 000000000..9f70bbc03 --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/clickup.mdx @@ -0,0 +1,293 @@ +--- +title: Integração com ClickUp +description: "Gerenciamento de tarefas e produtividade com integração ClickUp para CrewAI." +icon: "list-check" +--- + +## Visão Geral + +Permita que seus agentes gerenciem tarefas, projetos e fluxos de produtividade por meio do ClickUp. Crie e atualize tarefas, organize projetos, gerencie a designação de equipes e otimize o gerenciamento da sua produtividade com automação impulsionada por IA. + +## Pré-requisitos + +Antes de utilizar a integração com o ClickUp, certifique-se de que você possui: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa +- Uma conta ClickUp com as permissões apropriadas +- Sua conta ClickUp conectada pela [Página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com o ClickUp + +### 1. Conecte sua Conta ClickUp + +1. Acesse [CrewAI Enterprise Integrações](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **ClickUp** na seção Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para gerenciamento de tarefas e projetos +5. Copie seu Token Enterprise das [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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` + + + + **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. + + + + **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. + + + + **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. + + + + **Descrição:** Exclua uma tarefa no ClickUp. + + **Parâmetros:** + - `taskId` (string, obrigatório): ID da tarefa - O ID da tarefa a ser excluída. + + + + **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. + + + + **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. + + + + **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. + + + + **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. + + + + **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. + + + + **Descrição:** Obtenha informações de Membro no ClickUp. + + **Parâmetros:** Nenhum obrigatório. + + + +## Exemplos de Uso + +### Configuração Básica do Agente ClickUp + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Get enterprise tools (ClickUp tools will be included) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Create an agent with ClickUp capabilities +clickup_agent = Agent( + role="Task Manager", + goal="Manage tasks and projects in ClickUp efficiently", + backstory="An AI assistant specialized in task management and productivity coordination.", + tools=[enterprise_tools] +) + +# Task to create a new task +create_task = Task( + description="Create a task called 'Review Q1 Reports' in the Marketing list with high priority", + agent=clickup_agent, + expected_output="Task created successfully with task ID" +) + +# Run the task +crew = Crew( + agents=[clickup_agent], + tasks=[create_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do ClickUp + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Get only specific ClickUp tools +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["clickup_create_task", "clickup_update_task", "clickup_search_tasks"] +) + +task_coordinator = Agent( + role="Task Coordinator", + goal="Create and manage tasks efficiently", + backstory="An AI assistant that focuses on task creation and status management.", + tools=enterprise_tools +) + +# Task to manage task workflow +task_workflow = Task( + description="Create a task for project planning and assign it to the development team", + agent=task_coordinator, + expected_output="Task created and assigned successfully" +) + +crew = Crew( + agents=[task_coordinator], + tasks=[task_workflow] +) + +crew.kickoff() +``` + +### Gerenciamento Avançado de Projetos + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +project_manager = Agent( + role="Project Manager", + goal="Coordinate project activities and track team productivity", + backstory="An experienced project manager who ensures projects are delivered on time.", + tools=[enterprise_tools] +) + +# Complex task involving multiple ClickUp operations +project_coordination = Task( + description=""" + 1. Get all open tasks in the current space + 2. Identify overdue tasks and update their status + 3. Create a weekly report task summarizing project progress + 4. Assign the report task to the team lead + """, + agent=project_manager, + expected_output="Project status updated and weekly report task created and assigned" +) + +crew = Crew( + agents=[project_manager], + tasks=[project_coordination] +) + +crew.kickoff() +``` + +### Busca e Gerenciamento de Tarefas + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +task_analyst = Agent( + role="Task Analyst", + goal="Analyze task patterns and optimize team productivity", + backstory="An AI assistant that analyzes task data to improve team efficiency.", + tools=[enterprise_tools] +) + +# Task to analyze and optimize task distribution +task_analysis = Task( + description=""" + Search for all tasks assigned to team members in the last 30 days, + analyze completion patterns, and create optimization recommendations + """, + agent=task_analyst, + expected_output="Task analysis report with optimization recommendations" +) + +crew = Crew( + agents=[task_analyst], + tasks=[task_analysis] +) + +crew.kickoff() +``` + +### Precisa de Ajuda? + + + Entre em contato com nossa equipe de suporte para auxílio na configuração ou solução de problemas da integração com ClickUp. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/github.mdx b/docs/pt-BR/enterprise/integrations/github.mdx new file mode 100644 index 000000000..de2129386 --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/github.mdx @@ -0,0 +1,323 @@ +--- +title: Integração com GitHub +description: "Gerenciamento de repositórios e issues com a integração do GitHub para CrewAI." +icon: "github" +--- + +## Visão Geral + +Permita que seus agentes gerenciem repositórios, issues e releases através do GitHub. Crie e atualize issues, gerencie releases, acompanhe o desenvolvimento do projeto e otimize seu fluxo de trabalho de desenvolvimento de software com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração do GitHub, assegure-se de ter: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa +- Uma conta GitHub com permissões adequadas no repositório +- Conta do GitHub conectada através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com GitHub + +### 1. Conecte sua conta GitHub + +1. Acesse [Integrações CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **GitHub** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para gerenciamento de repositório e issues +5. Copie seu Token Enterprise nas [Configurações de Conta](https://app.crewai.com/crewai_plus/settings/account) + +### 2. Instale o pacote necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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"]`). + + + + **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` + + + + **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. + + + + **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` + + + + **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` + + + + **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` + + + + **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` + + + + **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. + + + + **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"). + + + + **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. + + + +## Exemplos de Uso + +### Configuração Básica de Agente GitHub + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Get enterprise tools (GitHub tools will be included) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Create an agent with GitHub capabilities +github_agent = Agent( + role="Repository Manager", + goal="Manage GitHub repositories, issues, and releases efficiently", + backstory="An AI assistant specialized in repository management and issue tracking.", + tools=[enterprise_tools] +) + +# Task to create a new issue +create_issue_task = Task( + description="Create a bug report issue for the login functionality in the main repository", + agent=github_agent, + expected_output="Issue created successfully with issue number" +) + +# Run the task +crew = Crew( + agents=[github_agent], + tasks=[create_issue_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas GitHub Específicas + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Get only specific GitHub tools +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["github_create_issue", "github_update_issue", "github_search_issue"] +) + +issue_manager = Agent( + role="Issue Manager", + goal="Create and manage GitHub issues efficiently", + backstory="An AI assistant that focuses on issue tracking and management.", + tools=enterprise_tools +) + +# Task to manage issue workflow +issue_workflow = Task( + description="Create a feature request issue and assign it to the development team", + agent=issue_manager, + expected_output="Feature request issue created and assigned successfully" +) + +crew = Crew( + agents=[issue_manager], + tasks=[issue_workflow] +) + +crew.kickoff() +``` + +### Gerenciamento de Releases + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +release_manager = Agent( + role="Release Manager", + goal="Manage software releases and versioning", + backstory="An experienced release manager who handles version control and release processes.", + tools=[enterprise_tools] +) + +# Task to create a new release +release_task = Task( + description=""" + Create a new release v2.1.0 for the project with: + - Auto-generated release notes + - Target the main branch + - Include a description of new features and bug fixes + """, + agent=release_manager, + expected_output="Release v2.1.0 created successfully with release notes" +) + +crew = Crew( + agents=[release_manager], + tasks=[release_task] +) + +crew.kickoff() +``` + +### Acompanhamento e Gerenciamento de Issues + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +project_coordinator = Agent( + role="Project Coordinator", + goal="Track and coordinate project issues and development progress", + backstory="An AI assistant that helps coordinate development work and track project progress.", + tools=[enterprise_tools] +) + +# Complex task involving multiple GitHub operations +coordination_task = Task( + description=""" + 1. Search for all open issues assigned to the current milestone + 2. Identify overdue issues and update their priority labels + 3. Create a weekly progress report issue + 4. Lock resolved issues that have been inactive for 30 days + """, + agent=project_coordinator, + expected_output="Project coordination completed with progress report and issue management" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[coordination_task] +) + +crew.kickoff() +``` + +### Obtendo Ajuda + + + 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. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/gmail.mdx b/docs/pt-BR/enterprise/integrations/gmail.mdx new file mode 100644 index 000000000..aa3c2edcb --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/gmail.mdx @@ -0,0 +1,356 @@ +--- +title: Integração com Gmail +description: "Gerenciamento de e-mails e contatos com a integração do Gmail para o CrewAI." +icon: "envelope" +--- + +## Visão Geral + +Permita que seus agentes gerenciem e-mails, contatos e rascunhos através do Gmail. Envie e-mails, pesquise mensagens, gerencie contatos, crie rascunhos e otimize suas comunicações por e-mail com automação impulsionada por IA. + +## Pré-requisitos + +Antes de usar a integração com o Gmail, certifique-se de que você possui: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa +- Uma conta do Gmail com as permissões adequadas +- Conectou sua conta do Gmail através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com o Gmail + +### 1. Conecte sua Conta do Gmail + +1. Navegue até [Integrações CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Gmail** na seção de Integrações de Autenticação +3. Clique em **Conectar** e conclua o fluxo OAuth +4. Conceda as permissões necessárias para o gerenciamento de e-mail e contato +5. Copie seu Token Empresarial em [Configurações de Conta](https://app.crewai.com/crewai_plus/settings/account) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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 " + } + ``` + + + + **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. + + + + **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" + } + ``` + + + + **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. + + + + **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" + } + ] + } + ``` + + + + **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. + + + + **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. + + + + **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. + + + + **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 " + } + ``` + + + +## Exemplos de Uso + +### Configuração Básica de Agente Gmail + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Get enterprise tools (Gmail tools will be included) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Create an agent with Gmail capabilities +gmail_agent = Agent( + role="Email Manager", + goal="Manage email communications and contacts efficiently", + backstory="An AI assistant specialized in email management and communication.", + tools=[enterprise_tools] +) + +# Task to send a follow-up email +send_email_task = Task( + description="Send a follow-up email to john@example.com about the project update meeting", + agent=gmail_agent, + expected_output="Email sent successfully with confirmation" +) + +# Run the task +crew = Crew( + agents=[gmail_agent], + tasks=[send_email_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Gmail + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Get only specific Gmail tools +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["gmail_send_email", "gmail_search_for_email", "gmail_create_draft"] +) + +email_coordinator = Agent( + role="Email Coordinator", + goal="Coordinate email communications and manage drafts", + backstory="An AI assistant that focuses on email coordination and draft management.", + tools=enterprise_tools +) + +# Task to prepare and send emails +email_coordination = Task( + description="Search for emails from the marketing team, create a summary draft, and send it to stakeholders", + agent=email_coordinator, + expected_output="Summary email sent to stakeholders" +) + +crew = Crew( + agents=[email_coordinator], + tasks=[email_coordination] +) + +crew.kickoff() +``` + +### Gerenciamento de Contatos + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +contact_manager = Agent( + role="Contact Manager", + goal="Manage and organize email contacts efficiently", + backstory="An experienced contact manager who maintains organized contact databases.", + tools=[enterprise_tools] +) + +# Task to manage contacts +contact_task = Task( + description=""" + 1. Search for contacts from the 'example.com' domain + 2. Create new contacts for recent email senders not in the contact list + 3. Update contact information with recent interaction data + """, + agent=contact_manager, + expected_output="Contact database updated with new contacts and recent interactions" +) + +crew = Crew( + agents=[contact_manager], + tasks=[contact_task] +) + +crew.kickoff() +``` + +### Pesquisa e Análise de E-mails + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +email_analyst = Agent( + role="Email Analyst", + goal="Analyze email patterns and provide insights", + backstory="An AI assistant that analyzes email data to provide actionable insights.", + tools=[enterprise_tools] +) + +# Task to analyze email patterns +analysis_task = Task( + description=""" + Search for all unread emails from the last 7 days, + categorize them by sender domain, + and create a summary report of communication patterns + """, + agent=email_analyst, + expected_output="Email analysis report with communication patterns and recommendations" +) + +crew = Crew( + agents=[email_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### Fluxos de Trabalho Automatizados de E-mail + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +workflow_manager = Agent( + role="Email Workflow Manager", + goal="Automate email workflows and responses", + backstory="An AI assistant that manages automated email workflows and responses.", + tools=[enterprise_tools] +) + +# Complex task involving multiple Gmail operations +workflow_task = Task( + description=""" + 1. Search for emails with 'urgent' in the subject from the last 24 hours + 2. Create draft responses for each urgent email + 3. Send automated acknowledgment emails to senders + 4. Create a summary report of urgent items requiring attention + """, + agent=workflow_manager, + expected_output="Urgent emails processed with automated responses and summary report" +) + +crew = Crew( + agents=[workflow_manager], + tasks=[workflow_task] +) + +crew.kickoff() +``` + +### Precisa de Ajuda? + + + Entre em contato com nosso time de suporte para obter assistência na configuração ou solução de problemas da integração Gmail. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/google_calendar.mdx b/docs/pt-BR/enterprise/integrations/google_calendar.mdx new file mode 100644 index 000000000..1576c83c8 --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/google_calendar.mdx @@ -0,0 +1,391 @@ +--- +title: Integração com Google Calendar +description: "Gerenciamento de eventos e agendas com integração ao Google Calendar para o CrewAI." +icon: "calendar" +--- + +## Visão Geral + +Permita que seus agentes gerenciem eventos de calendário, agendas e disponibilidade através do Google Calendar. Crie e atualize eventos, gerencie participantes, verifique disponibilidade e otimize seu fluxo de agendamento com automação potencializada por IA. + +## Pré-requisitos + +Antes de usar a integração com o Google Calendar, certifique-se de ter: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa +- Uma conta Google com acesso ao Google Calendar +- Sua conta Google conectada pela [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com Google Calendar + +### 1. Conecte sua Conta Google + +1. Acesse [Integrações do CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Google Calendar** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para acesso ao calendário e contatos +5. Copie seu Token Enterprise nas [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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. + + + + **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. + + + + **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"). + + + + **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. + + + + **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. + + + + **Descrição:** Obtém contatos do Google Calendar. + + **Parâmetros:** + - `paginationParameters` (objeto, opcional): Parâmetros de Paginação. + ```json + { + "pageCursor": "page_cursor_string" + } + ``` + + + + **Descrição:** Pesquisa contatos no Google Calendar. + + **Parâmetros:** + - `query` (string, opcional): Termo de pesquisa para buscar contatos. + + + + **Descrição:** Lista pessoas do diretório. + + **Parâmetros:** + - `paginationParameters` (objeto, opcional): Parâmetros de Paginação. + ```json + { + "pageCursor": "page_cursor_string" + } + ``` + + + + **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" + } + ``` + + + + **Descrição:** Lista outros contatos. + + **Parâmetros:** + - `paginationParameters` (objeto, opcional): Parâmetros de Paginação. + ```json + { + "pageCursor": "page_cursor_string" + } + ``` + + + + **Descrição:** Pesquisa outros contatos. + + **Parâmetros:** + - `query` (string, opcional): Termo de pesquisa para buscar contatos. + + + + **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" + } + ] + ``` + + + +## Exemplos de Uso + +### Configuração Básica de Agente de Calendário + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Obter ferramentas empresariais (as ferramentas do Google Calendar serão incluídas) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Criar um agente com capacidades do Google Calendar +calendar_agent = Agent( + role="Schedule Manager", + goal="Gerenciar eventos de calendário e agendamento de maneira eficiente", + backstory="Um assistente de IA especializado em gerenciamento de agendas e coordenação de horários.", + tools=[enterprise_tools] +) + +# Tarefa de criação de reunião +create_meeting_task = Task( + description="Crie uma reunião diária de equipe amanhã às 9h com o time de desenvolvimento", + agent=calendar_agent, + expected_output="Reunião criada com sucesso com link do Google Meet" +) + +# Executar a tarefa +crew = Crew( + agents=[calendar_agent], + tasks=[create_meeting_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Calendário + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Obter apenas ferramentas específicas do Google Calendar +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["google_calendar_create_event", "google_calendar_list_events", "google_calendar_get_availability"] +) + +meeting_coordinator = Agent( + role="Meeting Coordinator", + goal="Coordenar reuniões e verificar disponibilidade", + backstory="Um assistente de IA que foca em agendamento de reuniões e gerenciamento de disponibilidade.", + tools=enterprise_tools +) + +# Tarefa para agendar reunião com verificação de disponibilidade +schedule_meeting = Task( + description="Verifique a disponibilidade para a próxima semana e agende uma reunião de revisão do projeto com os stakeholders", + agent=meeting_coordinator, + expected_output="Reunião agendada após verificação da disponibilidade de todos os participantes" +) + +crew = Crew( + agents=[meeting_coordinator], + tasks=[schedule_meeting] +) + +crew.kickoff() +``` + +### Gerenciamento e Atualização de Eventos + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +event_manager = Agent( + role="Event Manager", + goal="Gerenciar e atualizar eventos de calendário de forma eficiente", + backstory="Um experiente gestor de eventos responsável pela logística e atualizações dos eventos.", + tools=[enterprise_tools] +) + +# Tarefa para gerenciar atualizações de eventos +event_management = Task( + description=""" + 1. Liste todos os eventos desta semana + 2. Atualize os eventos que precisarem de alteração de local para incluir links de videoconferência + 3. Envie convites de calendário para novos membros do time para reuniões recorrentes + """, + agent=event_manager, + expected_output="Eventos semanais atualizados com os locais corretos e novos participantes incluídos" +) + +crew = Crew( + agents=[event_manager], + tasks=[event_management] +) + +crew.kickoff() +``` + +### Gerenciamento de Contatos e Disponibilidade + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +availability_coordinator = Agent( + role="Availability Coordinator", + goal="Coordenar disponibilidade e gerenciar contatos para agendamento", + backstory="Um assistente de IA que se especializa em gerenciamento de disponibilidade e coordenação de contatos.", + tools=[enterprise_tools] +) + +# Tarefa de coordenação de disponibilidade +availability_task = Task( + description=""" + 1. Pesquise contatos no departamento de engenharia + 2. Verifique a disponibilidade de todos os engenheiros para a próxima sexta-feira à tarde + 3. Crie uma reunião de equipe no primeiro intervalo de 2 horas disponível + 4. Inclua o link do Google Meet e envie convites + """, + agent=availability_coordinator, + expected_output="Reunião agendada com base na disponibilidade com todos os engenheiros convidados" +) + +crew = Crew( + agents=[availability_coordinator], + tasks=[availability_task] +) + +crew.kickoff() +``` + +### Workflows de Agendamento Automatizado + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +scheduling_automator = Agent( + role="Scheduling Automator", + goal="Automatizar workflows de agendamento e gerenciamento de calendários", + backstory="Um assistente de IA que automatiza cenários complexos de agendamento e workflows de agenda.", + tools=[enterprise_tools] +) + +# Tarefa de automação de agendamento complexo +automation_task = Task( + description=""" + 1. Liste todos os eventos futuros das próximas duas semanas + 2. Identifique conflitos de agendamento ou reuniões consecutivas + 3. Sugira horários ótimos de reunião verificando as disponibilidades + 4. Crie intervalos entre reuniões quando necessário + 5. Atualize a descrição dos eventos com pautas e links de reunião + """, + agent=scheduling_automator, + expected_output="Calendário otimizado com conflitos resolvidos, intervalos e detalhes das reuniões atualizados" +) + +crew = Crew( + agents=[scheduling_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Autenticação** +- Certifique-se de que sua conta Google possui as permissões necessárias para acessar o calendário +- Verifique se a conexão OAuth inclui todos os escopos necessários para a API do Google Calendar +- Confirme se as configurações de compartilhamento do calendário permitem o nível de acesso necessário + +**Problemas na Criação de Eventos** +- Verifique se os formatos de horário estão corretos (ISO8601 ou timestamps Unix) +- Assegure-se de que os endereços de e-mail dos participantes estão corretamente formatados +- Verifique se o calendário de destino existe e está acessível +- Confirme se os fusos horários estão especificados corretamente + +**Disponibilidade e Conflitos de Horário** +- Use formato ISO adequado para os intervalos de horário ao verificar disponibilidade +- Certifique-se de que os fusos horários estão consistentes em todas as operações +- Verifique se os IDs dos calendários estão corretos ao consultar múltiplos calendários + +**Pesquisa de Contatos e Pessoas** +- Assegure-se de que os termos de pesquisa estão devidamente formatados +- Verifique se as permissões para acesso ao diretório foram concedidas +- Certifique-se de que as informações de contato estão atualizadas e acessíveis + +**Atualização e Exclusão de Eventos** +- Verifique se os IDs dos eventos estão corretos e se os eventos existem +- Assegure-se de que você possui permissões de edição para os eventos +- Verifique se a propriedade do calendário permite modificações + +### Obtendo Ajuda + + + 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. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/google_sheets.mdx b/docs/pt-BR/enterprise/integrations/google_sheets.mdx new file mode 100644 index 000000000..92ef39665 --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/google_sheets.mdx @@ -0,0 +1,321 @@ +--- +title: Integração com Google Sheets +description: "Sincronização de dados de planilhas com a integração do Google Sheets para CrewAI." +icon: "google" +--- + +## Visão Geral + +Permita que seus agentes gerenciem dados de planilhas por meio do Google Sheets. Leia linhas, crie novos registros, atualize dados existentes e otimize os fluxos de trabalho de gerenciamento de dados com automação alimentada por IA. Perfeito para acompanhamento de dados, relatórios e gestão colaborativa de informações. + +## Pré-requisitos + +Antes de utilizar a integração com o Google Sheets, certifique-se de que você possui: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa +- Uma conta Google com acesso ao Google Sheets +- Sua conta Google conectada pela [página de integrações](https://app.crewai.com/crewai_plus/connectors) +- Planilhas com cabeçalhos de coluna adequados para operações com dados + +## Configurando a Integração com Google Sheets + +### 1. Conecte sua Conta Google + +1. Acesse [Integrações do CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors) +2. Localize **Google Sheets** na seção Integrações de Autenticação +3. Clique em **Conectar** e conclua o fluxo OAuth +4. Conceda as permissões necessárias para acesso à planilha +5. Copie seu Token Enterprise em [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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. + + + + **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" + } + ``` + + + + **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" + } + ``` + + + +## Exemplos de Uso + +### Configuração Básica de um Agente Google Sheets + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Obtenha as ferramentas enterprise (ferramentas Google Sheets incluídas) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Crie um agente com capacidades para Google Sheets +sheets_agent = Agent( + role="Data Manager", + goal="Gerenciar dados de planilha e rastrear informações de maneira eficiente", + backstory="Um assistente de IA especializado em gestão de dados e operações em planilhas.", + tools=[enterprise_tools] +) + +# Tarefa para adicionar novos dados a uma planilha +data_entry_task = Task( + description="Adicionar novo registro de cliente na planilha de banco de dados de clientes com nome, e-mail e data de cadastro", + agent=sheets_agent, + expected_output="Novo registro de cliente adicionado com sucesso à planilha" +) + +# Execute a tarefa +crew = Crew( + agents=[sheets_agent], + tasks=[data_entry_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Google Sheets + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Obtenha apenas ferramentas específicas do Google Sheets +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["google_sheets_get_row", "google_sheets_create_row"] +) + +data_collector = Agent( + role="Data Collector", + goal="Coletar e organizar dados em planilhas", + backstory="Um assistente de IA dedicado à coleta e organização de dados.", + tools=enterprise_tools +) + +# Tarefa para coletar e organizar dados +data_collection = Task( + description="Recuperar dados atuais de inventário e adicionar novos produtos à planilha de inventário", + agent=data_collector, + expected_output="Dados de inventário recuperados e novos produtos adicionados com sucesso" +) + +crew = Crew( + agents=[data_collector], + tasks=[data_collection] +) + +crew.kickoff() +``` + +### Análise de Dados e Geração de Relatórios + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +data_analyst = Agent( + role="Data Analyst", + goal="Analisar dados de planilhas e gerar insights", + backstory="Um analista de dados experiente que extrai insights dos dados de planilhas.", + tools=[enterprise_tools] +) + +# Tarefa para analisar dados e criar relatórios +analysis_task = Task( + description=""" + 1. Recuperar todos os dados de vendas da planilha do mês atual + 2. Analisar os dados em busca de tendências e padrões + 3. Criar um relatório resumo em uma nova linha com os principais indicadores + """, + agent=data_analyst, + expected_output="Dados de vendas analisados e relatório resumo criado com os principais insights" +) + +crew = Crew( + agents=[data_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### Atualizações Automatizadas de Dados + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +data_updater = Agent( + role="Data Updater", + goal="Atualizar e manter dados de planilhas automaticamente", + backstory="Um assistente de IA que mantém a precisão dos dados e atualiza registros automaticamente.", + tools=[enterprise_tools] +) + +# Tarefa para atualizar dados com base em condições +update_task = Task( + description=""" + 1. Encontrar todos os pedidos pendentes na planilha de pedidos + 2. Atualizar o status para 'processing' + 3. Adicionar um registro de data/hora da atualização do status + 4. Registrar as alterações em uma planilha de acompanhamento separada + """, + agent=data_updater, + expected_output="Todos os pedidos pendentes atualizados para o status processing com registros de data/hora" +) + +crew = Crew( + agents=[data_updater], + tasks=[update_task] +) + +crew.kickoff() +``` + +### Fluxo de Trabalho Complexo com Dados + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +workflow_manager = Agent( + role="Data Workflow Manager", + goal="Gerenciar fluxos de dados complexos entre várias planilhas", + backstory="Um assistente de IA que orquestra operações complexas de dados entre várias planilhas.", + tools=[enterprise_tools] +) + +# Tarefa de workflow complexa +workflow_task = Task( + description=""" + 1. Obter todos os dados de clientes da planilha principal de clientes + 2. Criar registros de resumo mensal para clientes ativos + 3. Atualizar o status de clientes com base na atividade nos últimos 30 dias + 4. Gerar um relatório mensal com métricas dos clientes + 5. Arquivar registros de clientes inativos em uma planilha separada + """, + agent=workflow_manager, + expected_output="Workflow mensal de clientes concluído com atualizações de status e relatórios gerados" +) + +crew = Crew( + agents=[workflow_manager], + tasks=[workflow_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Permissão** +- Certifique-se de que sua conta Google tem acesso de edição às planilhas alvo +- Verifique se a conexão OAuth inclui os escopos necessários para a API do Google Sheets +- Confira se as planilhas estão compartilhadas com a conta autenticada + +**Problemas de Estrutura da Planilha** +- Certifique-se de que as worksheets têm cabeçalhos de coluna antes de criar ou atualizar linhas +- Verifique se os nomes das colunas em `additionalFields` correspondem exatamente aos cabeçalhos +- Confirme que a worksheet especificada existe na planilha + +**Problemas de Tipo e Formato de Dados** +- Garanta que os valores dos dados estejam no formato esperado para cada coluna +- Utilize formatos de data adequados nas colunas de data (recomenda-se ISO) +- Verifique se valores numéricos estão devidamente formatados para colunas numéricas + +**Problemas com Fórmulas de Filtro** +- Certifique-se de que as fórmulas de filtro seguem a estrutura JSON correta para forma normal disjuntiva +- Use nomes de campos válidos, correspondendo exatamente aos cabeçalhos das colunas +- Teste filtros simples antes de criar consultas com múltiplas condições +- Verifique se os tipos de operadores correspondem aos tipos de dados das colunas + +**Limites de Linhas e Performance** +- Fique atento aos limites de linhas ao usar `GOOGLE_SHEETS_GET_ROW` +- Considere paginação para grandes volumes de dados +- Use filtros específicos para reduzir a quantidade de dados processados + +**Operações de Atualização** +- Certifique-se de que as condições de filtro identifiquem corretamente as linhas a serem atualizadas +- Teste condições de filtro com pequenos conjuntos de dados antes de grandes atualizações +- Verifique se todos os campos obrigatórios estão incluídos nas operações de atualização + +### Obtendo Ajuda + + + 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. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/hubspot.mdx b/docs/pt-BR/enterprise/integrations/hubspot.mdx new file mode 100644 index 000000000..a3ba212da --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/hubspot.mdx @@ -0,0 +1,579 @@ +--- +title: "Integração com HubSpot" +description: "Gerencie empresas e contatos no HubSpot com o CrewAI." +icon: "briefcase" +--- + +## Visão Geral + +Permita que seus agentes gerenciem empresas e contatos dentro do HubSpot. Crie novos registros e otimize seus processos de CRM com automação baseada em IA. + +## Pré-requisitos + +Antes de utilizar a integração com o HubSpot, certifique-se de que você possui: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa. +- Uma conta HubSpot com permissões adequadas. +- Sua conta HubSpot conectada pela [página de Integrações](https://app.crewai.com/crewai_plus/connectors). + +## Configurando a Integração com o HubSpot + +### 1. Conecte Sua Conta HubSpot + +1. Navegue até [CrewAI Enterprise Integrações](https://app.crewai.com/crewai_plus/connectors). +2. Encontre **HubSpot** na seção de Integrações de Autenticação. +3. Clique em **Conectar** e complete o fluxo OAuth. +4. Conceda as permissões necessárias para gerenciamento de empresas e contatos. +5. Copie o seu Token Enterprise nas [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account). + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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. + + + + **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. + + + + **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`. + + + + **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`) + + + + **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. + + + + **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. + + + + **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. + + + + **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. + + + + **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. + + + + **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. + + + + **Descrição:** Obtenha uma lista de registros de empresas do HubSpot. + + **Parâmetros:** + - `paginationParameters` (object, opcional): Use `pageCursor` para buscar páginas subsequentes. + + + + **Descrição:** Obtenha uma lista de registros de contatos do HubSpot. + + **Parâmetros:** + - `paginationParameters` (object, opcional): Use `pageCursor` para buscar páginas subsequentes. + + + + **Descrição:** Obtenha uma lista de registros de negócios do HubSpot. + + **Parâmetros:** + - `paginationParameters` (object, opcional): Use `pageCursor` para buscar páginas subsequentes. + + + + **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. + + + + **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. + + + + **Descrição:** Obtenha um registro de empresa pelo seu ID. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID da empresa a ser consultada. + + + + **Descrição:** Obtenha um registro de contato pelo seu ID. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do contato a ser consultado. + + + + **Descrição:** Obtenha um registro de negócio pelo seu ID. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do negócio a ser consultado. + + + + **Descrição:** Obtenha um registro de engajamento pelo seu ID. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do engajamento a ser consultado. + + + + **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. + + + + **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. + + + + **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. + + + + **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. + + + + **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. + + + + **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. + + + + **Descrição:** Exclua um registro de empresa pelo seu ID. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID da empresa a ser excluída. + + + + **Descrição:** Exclua um registro de contato pelo seu ID. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do contato a ser excluído. + + + + **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. + + + + **Descrição:** Exclua um registro de engajamento pelo seu ID. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do engajamento a ser excluído. + + + + **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. + + + + **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. + + + + **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'). + + + +## Exemplos de Uso + +### Configuração Básica de Agente HubSpot + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Obtenha as ferramentas enterprise (ferramentas HubSpot incluídas) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Crie um agente com capacidades HubSpot +hubspot_agent = Agent( + role="CRM Manager", + goal="Manage company and contact records in HubSpot", + backstory="An AI assistant specialized in CRM management.", + tools=[enterprise_tools] +) + +# Task para criar nova empresa +create_company_task = Task( + description="Create a new company in HubSpot with name 'Innovate Corp' and domain 'innovatecorp.com'.", + agent=hubspot_agent, + expected_output="Company created successfully with confirmation" +) + +# Execute a tarefa +crew = Crew( + agents=[hubspot_agent], + tasks=[create_company_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas HubSpot Específicas + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Obtenha somente a ferramenta para criar contatos +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["hubspot_create_record_contacts"] +) + +contact_creator = Agent( + role="Contact Creator", + goal="Create new contacts in HubSpot", + backstory="An AI assistant that focuses on creating new contact entries in the CRM.", + tools=[enterprise_tools] +) + +# Task para criar contato +create_contact = Task( + description="Create a new contact for 'John Doe' with email 'john.doe@example.com'.", + agent=contact_creator, + expected_output="Contact created successfully in HubSpot." +) + +crew = Crew( + agents=[contact_creator], + tasks=[create_contact] +) + +crew.kickoff() +``` + +### Gerenciamento de Contatos + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +crm_manager = Agent( + role="CRM Manager", + goal="Manage and organize HubSpot contacts efficiently.", + backstory="An experienced CRM manager who maintains an organized contact database.", + tools=[enterprise_tools] +) + +# Task para gerenciar contatos +contact_task = Task( + description="Create a new contact for 'Jane Smith' at 'Global Tech Inc.' with email 'jane.smith@globaltech.com'.", + agent=crm_manager, + expected_output="Contact database updated with the new contact." +) + +crew = Crew( + agents=[crm_manager], + tasks=[contact_task] +) + +crew.kickoff() +``` + +### Precisa de Ajuda? + + + Entre em contato com nossa equipe de suporte para assistência na configuração ou solução de problemas com a integração HubSpot. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/jira.mdx b/docs/pt-BR/enterprise/integrations/jira.mdx new file mode 100644 index 000000000..8a6732340 --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/jira.mdx @@ -0,0 +1,394 @@ +--- +title: Integração com Jira +description: "Rastreamento de problemas e gestão de projetos com a integração Jira para CrewAI." +icon: "bug" +--- + +## Visão Geral + +Permita que seus agentes gerenciem problemas, projetos e fluxos de trabalho pelo Jira. Crie e atualize issues, acompanhe o progresso de projetos, gerencie atribuições e otimize sua gestão de projetos com automação potencializada por IA. + +## Pré-requisitos + +Antes de usar a integração com o Jira, certifique-se de ter: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa +- Uma conta Jira com permissões adequadas para o projeto +- Sua conta Jira conectada pela [Página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com o Jira + +### 1. Conectar Sua Conta Jira + +1. Acesse [Integrações CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Jira** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo do OAuth +4. Conceda as permissões necessárias para gestão de issues e projetos +5. Copie seu Token Enterprise em [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account) + +### 2. Instalar o Pacote Necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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" + } + ``` + + + + **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. + + + + **Descrição:** Obtém uma issue pelo identificador no Jira. + + **Parâmetros:** + - `issueKey` (string, obrigatório): Chave da Issue (exemplo: "TEST-1234"). + + + + **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. + + + + **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" + } + ``` + + + + **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. + + + + **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. + + + + **Descrição:** Obtém os projetos no Jira. + + **Parâmetros:** + - `paginationParameters` (object, opcional): Parâmetros de Paginação. + ```json + { + "pageCursor": "cursor_string" + } + ``` + + + + **Descrição:** Obtém os tipos de issues por projeto no Jira. + + **Parâmetros:** + - `project` (string, obrigatório): Chave do projeto. + + + + **Descrição:** Obtém todos os tipos de issues no Jira. + + **Parâmetros:** Nenhum obrigatório. + + + + **Descrição:** Obtém os status das issues de um projeto específico. + + **Parâmetros:** + - `project` (string, obrigatório): Chave do projeto. + + + + **Descrição:** Obtém os responsáveis por um projeto específico. + + **Parâmetros:** + - `project` (string, obrigatório): Chave do projeto. + + + +## Exemplos de Uso + +### Configuração Básica de um Agente Jira + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Obtenha as ferramentas enterprise (incluirá ferramentas do Jira) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Criação de um agente com capacidades Jira +jira_agent = Agent( + role="Issue Manager", + goal="Gerenciar issues do Jira e acompanhar o progresso do projeto de forma eficiente", + backstory="Um assistente de IA especializado em rastreamento de issues e gestão de projetos.", + tools=[enterprise_tools] +) + +# Tarefa para criar um relatório de bug +create_bug_task = Task( + description="Criar um relatório de bug para a funcionalidade de login com alta prioridade e designar para o time de desenvolvimento", + agent=jira_agent, + expected_output="Bug report creado com sucesso e chave da issue" +) + +# Executar a tarefa +crew = Crew( + agents=[jira_agent], + tasks=[create_bug_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Jira Específicas + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Obtenha apenas ferramentas Jira específicas +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["jira_create_issue", "jira_update_issue", "jira_search_by_jql"] +) + +issue_coordinator = Agent( + role="Issue Coordinator", + goal="Criar e gerenciar issues Jira de forma eficiente", + backstory="Um assistente de IA focado na criação e gestão de issues.", + tools=enterprise_tools +) + +# Tarefa para gerenciar workflow de issues +issue_workflow = Task( + description="Criar uma issue de solicitação de feature e atualizar o status de issues relacionadas", + agent=issue_coordinator, + expected_output="Feature request criada e issues relacionadas atualizadas" +) + +crew = Crew( + agents=[issue_coordinator], + tasks=[issue_workflow] +) + +crew.kickoff() +``` + +### Análise e Relatórios de Projeto + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +project_analyst = Agent( + role="Project Analyst", + goal="Analisar dados de projetos e gerar insights a partir do Jira", + backstory="Um analista de projetos experiente que extrai insights de dados de gestão de projetos.", + tools=[enterprise_tools] +) + +# Tarefa para analisar status do projeto +analysis_task = Task( + description=""" + 1. Obtenha todos os projetos e seus tipos de issues + 2. Busque todas as issues abertas entre projetos + 3. Analise distribuição de issues por status e responsável + 4. Crie uma issue de relatório de resumo com os achados + """, + agent=project_analyst, + expected_output="Análise do projeto completa com relatório de resumo criado" +) + +crew = Crew( + agents=[project_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### Gestão Automatizada de Issues + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +automation_manager = Agent( + role="Automation Manager", + goal="Automatizar gestão de issues e processos de workflow", + backstory="Um assistente de IA que automatiza tarefas repetitivas de gestão de issues.", + tools=[enterprise_tools] +) + +# Tarefa para automatizar gestão de issues +automation_task = Task( + description=""" + 1. Buscar todas as issues não atribuídas usando JQL + 2. Obter responsáveis disponíveis de cada projeto + 3. Atribuir issues automaticamente com base na carga de trabalho e especialidade + 4. Atualizar prioridades das issues baseando-se na idade e tipo + 5. Criar issues semanais de planejamento de sprint + """, + agent=automation_manager, + expected_output="Issues atribuídas automaticamente e issues de planejamento de sprint criadas" +) + +crew = Crew( + agents=[automation_manager], + tasks=[automation_task] +) + +crew.kickoff() +``` + +### Operações Avançadas Baseadas em Schema + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +schema_specialist = Agent( + role="Schema Specialist", + goal="Executar operações complexas no Jira usando schemas dinâmicos", + backstory="Um assistente de IA que manipula schemas dinâmicos e tipos de issues customizadas do Jira.", + tools=[enterprise_tools] +) + +# Tarefa usando operações baseadas em schema +schema_task = Task( + description=""" + 1. Obtenha todos os projetos e seus tipos personalizados de issues + 2. Para cada tipo personalizado, descreva o schema de ação + 3. Crie issues usando schema dinâmico para campos complexos customizados + 4. Atualize issues com valores de campos personalizados a partir de regras de negócio + """, + agent=schema_specialist, + expected_output="Issues customizadas criadas e atualizadas utilizando schemas dinâmicos" +) + +crew = Crew( + agents=[schema_specialist], + tasks=[schema_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Permissão** +- Certifique-se de que sua conta Jira tem as permissões necessárias nos projetos alvo +- Verifique se a conexão OAuth inclui os escopos necessários da API Jira +- Confira se você possui permissões de criar/editar issues nos projetos especificados + +**Chaves de Projeto ou Issue Inválidas** +- Confira o formato das chaves dos projetos e issues (ex: "PROJ-123") +- Verifique se os projetos existem e são acessíveis pela sua conta +- Certifique-se de que chaves de issues referenciam issues existentes + +**Problemas de Tipo ou Status de Issue** +- Use JIRA_GET_ISSUE_TYPES_BY_PROJECT para obter tipos válidos de issue para um projeto +- Use JIRA_GET_ISSUE_STATUS_BY_PROJECT para obter status válidos +- Certifique-se de que tipos e status de issue estão disponíveis no projeto alvo + +**Problemas com Queries JQL** +- Teste as queries JQL na busca de issues do Jira antes de utilizar em chamadas de API +- Certifique-se de que os nomes dos campos em JQL estejam corretos e existam em sua instância do Jira +- Use a sintaxe correta de JQL para queries complexas + +**Problemas com Campos Customizados e Schemas** +- Use JIRA_DESCRIBE_ACTION_SCHEMA para obter o schema correto para tipos de issues complexas +- Certifique-se de que os IDs dos campos customizados estão corretos (ex: "customfield_10001") +- Verifique se esses campos estão disponíveis no projeto e tipo de issue alvo + +**Problemas de Fórmulas de Filtro** +- Garanta que as fórmulas de filtro sigam a estrutura JSON correta para forma normal disjuntiva +- Use apenas campos válidos conforme configuração do seu Jira +- Teste filtros simples antes de construir queries complexas com múltiplas condições + +### Obtenha Ajuda + + + Entre em contato com nosso time de suporte para obter assistência na configuração ou solução de problemas da integração Jira. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/linear.mdx b/docs/pt-BR/enterprise/integrations/linear.mdx new file mode 100644 index 000000000..78b2cca45 --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/linear.mdx @@ -0,0 +1,453 @@ +--- +title: Integração com o Linear +description: "Acompanhamento de projetos de software e rastreamento de bugs com a integração Linear para CrewAI." +icon: "list-check" +--- + +## Visão Geral + +Permita que seus agentes gerenciem issues, projetos e fluxos de trabalho de desenvolvimento através do Linear. Crie e atualize issues, gerencie cronogramas de projetos, organize equipes e otimize seu processo de desenvolvimento de software com automação impulsionada por IA. + +## Pré-requisitos + +Antes de utilizar a integração com o Linear, certifique-se de que você possui: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com uma assinatura ativa +- Uma conta Linear com permissões apropriadas no workspace +- Conectou sua conta Linear através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com o Linear + +### 1. Conecte sua Conta Linear + +1. Navegue até [Integrações CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Linear** na seção Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para gerenciamento de issues e projetos +5. Copie seu Token Empresarial em [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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"] + } + ``` + + + + **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"] + } + ``` + + + + **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"). + + + + **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"). + + + + **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` + + + + **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"). + + + + **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"). + + + + **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" + } + ``` + + + + **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": "" + } + ``` + + + + **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": "" + } + ``` + + + + **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"). + + + + **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"). + + + + **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` + + + +## Exemplos de Uso + +### Configuração Básica do Agente Linear + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Obtenha ferramentas empresariais (ferramentas do Linear serão incluídas) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Crie um agente com funcionalidades do Linear +linear_agent = Agent( + role="Development Manager", + goal="Gerenciar issues do Linear e acompanhar o progresso do desenvolvimento de forma eficiente", + backstory="Um assistente de IA especializado em gerenciamento de projetos de desenvolvimento de software.", + tools=[enterprise_tools] +) + +# Tarefa para criar um relatório de bug +create_bug_task = Task( + description="Crie um relatório de bug de alta prioridade para o sistema de autenticação e atribua à equipe de backend", + agent=linear_agent, + expected_output="Bug report criado com sucesso com ID da issue" +) + +# Execute a tarefa +crew = Crew( + agents=[linear_agent], + tasks=[create_bug_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Lineares Específicas + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Obtenha apenas ferramentas lineares específicas +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["linear_create_issue", "linear_update_issue", "linear_search_issue"] +) + +issue_manager = Agent( + role="Issue Manager", + goal="Criar e gerenciar issues no Linear de forma eficiente", + backstory="Um assistente de IA focado na criação e no gerenciamento do ciclo de vida de issues.", + tools=enterprise_tools +) + +# Tarefa para gerenciar fluxo de issues +issue_workflow = Task( + description="Crie uma issue de solicitação de recurso e atualize os status das issues relacionadas para refletir o progresso atual", + agent=issue_manager, + expected_output="Solicitação de recurso criada e issues relacionadas atualizadas" +) + +crew = Crew( + agents=[issue_manager], + tasks=[issue_workflow] +) + +crew.kickoff() +``` + +### Gerenciamento de Projetos e Equipes + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +project_coordinator = Agent( + role="Project Coordinator", + goal="Coordenar projetos e equipes no Linear de forma eficiente", + backstory="Um coordenador de projetos experiente que gerencia ciclos de desenvolvimento e fluxos de trabalho de equipe.", + tools=[enterprise_tools] +) + +# Tarefa para coordenar a configuração de projeto +project_coordination = Task( + description=""" + 1. Pesquise por equipes de engenharia no Linear + 2. Crie um novo projeto para o desenvolvimento de recursos do Q2 + 3. Associe o projeto às equipes relevantes + 4. Crie marcos iniciais do projeto como issues + """, + agent=project_coordinator, + expected_output="Projeto Q2 criado com equipes atribuídas e marcos iniciais estabelecidos" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[project_coordination] +) + +crew.kickoff() +``` + +### Hierarquia de Issues e Gerenciamento de Sub-tarefas + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +task_organizer = Agent( + role="Task Organizer", + goal="Organizar issues complexas em sub-tarefas gerenciáveis", + backstory="Um assistente de IA que divide trabalhos de desenvolvimento complexos em sub-tarefas organizadas.", + tools=[enterprise_tools] +) + +# Tarefa para criar hierarquia de issues +hierarchy_task = Task( + description=""" + 1. Pesquise por issues de recursos grandes que precisam ser divididos + 2. Para cada issue complexa, crie sub-issues para diferentes componentes + 3. Atualize as issues principais com descrições adequadas e links para sub-issues + 4. Atribua sub-issues aos membros apropriados da equipe com base na especialidade + """, + agent=task_organizer, + expected_output="Issues complexas divididas em sub-tarefas gerenciáveis com atribuições corretas" +) + +crew = Crew( + agents=[task_organizer], + tasks=[hierarchy_task] +) + +crew.kickoff() +``` + +### Fluxo de Trabalho de Desenvolvimento Automatizado + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +workflow_automator = Agent( + role="Workflow Automator", + goal="Automatizar processos de fluxo de trabalho de desenvolvimento no Linear", + backstory="Um assistente de IA que automatiza tarefas repetitivas de fluxo de trabalho de desenvolvimento.", + tools=[enterprise_tools] +) + +# Tarefa de automação de workflow complexa +automation_task = Task( + description=""" + 1. Pesquise por issues que estejam em progresso há mais de 7 dias + 2. Atualize suas prioridades com base nas datas de vencimento e importância do projeto + 3. Crie issues semanais de planejamento de sprint para cada equipe + 4. Arquive issues concluídas do ciclo anterior + 5. Gere relatórios de status do projeto como novas issues + """, + agent=workflow_automator, + expected_output="Fluxo de desenvolvimento automatizado com prioridades atualizadas, planejamento de sprint e relatórios de status" +) + +crew = Crew( + agents=[workflow_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Permissão** +- Certifique-se de que sua conta Linear possui as permissões necessárias no workspace de destino +- Verifique se a conexão OAuth inclui os escopos requeridos pela API do Linear +- Confirme se você tem permissões para criar/editar issues e projetos no workspace + +**IDs e Referências Inválidas** +- Verifique os IDs de equipes, IDs de issues e IDs de projetos para garantir o formato UUID correto +- Assegure que as entidades referenciadas (equipes, projetos, ciclos) existem e estão acessíveis +- Verifique se os identificadores de issues seguem o formato correto (ex: "ABC-1") + +**Problemas de Associação entre Equipe e Projeto** +- Use LINEAR_SEARCH_TEAMS para obter IDs de equipe válidos antes de criar issues ou projetos +- Certifique-se de que as equipes existem e estão ativas no seu workspace +- Verifique se os IDs das equipes estão devidamente formatados como UUIDs + +**Problemas com Status e Prioridade das Issues** +- Verifique se os IDs de status referenciam estados de workflow válidos para a equipe +- Certifique-se de que os valores de prioridade estão dentro do intervalo válido para sua configuração do Linear +- Confirme que campos personalizados e labels existem antes de referenciá-los + +**Problemas com Formato de Data e Hora** +- Use o formato ISO 8601 para datas de vencimento e timestamps +- Certifique-se de que os fusos horários estão corretos para cálculos de datas de vencimento +- Verifique se os valores de data são válidos e posteriores à data atual para datas de vencimento + +**Problemas de Pesquisa e Filtros** +- Garanta que as consultas de busca estejam formatadas corretamente e não estejam vazias +- Utilize nomes de campos válidos nas fórmulas de filtro: `title`, `number`, `project`, `createdAt` +- Teste filtros simples antes de montar consultas complexas com múltiplas condições +- Verifique se os tipos de operadores correspondem aos tipos de dados dos campos filtrados + +**Problemas na Criação de Sub-issues** +- Certifique-se de que os IDs das issues pai são válidos e acessíveis +- Verifique se o ID da equipe para as sub-issues corresponde ou é compatível com o da issue pai +- Assegure-se de que as issues pai não estejam arquivadas ou excluídas + +### Obtendo Ajuda + + + 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. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/notion.mdx b/docs/pt-BR/enterprise/integrations/notion.mdx new file mode 100644 index 000000000..70916d9fc --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/notion.mdx @@ -0,0 +1,509 @@ +--- +title: Integração com o Notion +description: "Gerenciamento de páginas e bancos de dados com integração do Notion para o CrewAI." +icon: "book" +--- + +## Visão Geral + +Permita que seus agentes gerenciem páginas, bancos de dados e conteúdos através do Notion. Crie e atualize páginas, gerencie blocos de conteúdo, organize bases de conhecimento e otimize seus fluxos de documentação com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração com o Notion, certifique-se de que você tem: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa +- Uma conta Notion com permissões adequadas no workspace +- Sua conta Notion conectada através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com o Notion + +### 1. Conecte sua Conta Notion + +1. Acesse [Integrações do CrewAI Enterprise](https://app.crewai.com/crewai_plus/connectors) +2. Procure por **Notion** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo de OAuth +4. Conceda as permissões necessárias para gerenciamento de páginas e bancos de dados +5. Copie seu Token Enterprise em [Configurações da Conta](https://app.crewai.com/crewai_plus/settings/account) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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" + } + } + ``` + + + + **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" + } + } + ``` + + + + **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"). + + + + **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"). + + + + **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` + + + + **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"). + + + + **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" + } + } + ``` + + + + **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"). + + + + **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"). + + + +## Exemplos de Uso + +### Configuração Básica do Agente Notion + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Get enterprise tools (Notion tools will be included) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Create an agent with Notion capabilities +notion_agent = Agent( + role="Documentation Manager", + goal="Manage documentation and knowledge base in Notion efficiently", + backstory="An AI assistant specialized in content management and documentation.", + tools=[enterprise_tools] +) + +# Task to create a meeting notes page +create_notes_task = Task( + description="Create a new meeting notes page in the team database with today's date and agenda items", + agent=notion_agent, + expected_output="Meeting notes page created successfully with structured content" +) + +# Run the task +crew = Crew( + agents=[notion_agent], + tasks=[create_notes_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Notion + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Get only specific Notion tools +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["notion_create_page", "notion_update_block", "notion_search_pages"] +) + +content_manager = Agent( + role="Content Manager", + goal="Create and manage content pages efficiently", + backstory="An AI assistant that focuses on content creation and management.", + tools=enterprise_tools +) + +# Task to manage content workflow +content_workflow = Task( + description="Create a new project documentation page and add structured content blocks for requirements and specifications", + agent=content_manager, + expected_output="Project documentation created with organized content sections" +) + +crew = Crew( + agents=[content_manager], + tasks=[content_workflow] +) + +crew.kickoff() +``` + +### Gerenciamento de Base de Conhecimento + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +knowledge_curator = Agent( + role="Knowledge Curator", + goal="Curate and organize knowledge base content in Notion", + backstory="An experienced knowledge manager who organizes and maintains comprehensive documentation.", + tools=[enterprise_tools] +) + +# Task to curate knowledge base +curation_task = Task( + description=""" + 1. Search for existing documentation pages related to our new product feature + 2. Create a comprehensive feature documentation page with proper structure + 3. Add code examples, images, and links to related resources + 4. Update existing pages with cross-references to the new documentation + """, + agent=knowledge_curator, + expected_output="Feature documentation created and integrated with existing knowledge base" +) + +crew = Crew( + agents=[knowledge_curator], + tasks=[curation_task] +) + +crew.kickoff() +``` + +### Estrutura e Organização de Conteúdo + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +content_organizer = Agent( + role="Content Organizer", + goal="Organize and structure content blocks for optimal readability", + backstory="An AI assistant that specializes in content structure and user experience.", + tools=[enterprise_tools] +) + +# Task to organize content structure +organization_task = Task( + description=""" + 1. Get content from existing project pages + 2. Analyze the structure and identify improvement opportunities + 3. Update content blocks to use proper headings, tables, and formatting + 4. Add table of contents and improve navigation between related pages + 5. Create templates for future documentation consistency + """, + agent=content_organizer, + expected_output="Content reorganized with improved structure and navigation" +) + +crew = Crew( + agents=[content_organizer], + tasks=[organization_task] +) + +crew.kickoff() +``` + +### Fluxos de Trabalho de Documentação Automatizados + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +doc_automator = Agent( + role="Documentation Automator", + goal="Automate documentation workflows and maintenance", + backstory="An AI assistant that automates repetitive documentation tasks.", + tools=[enterprise_tools] +) + +# Complex documentation automation task +automation_task = Task( + description=""" + 1. Search for pages that haven't been updated in the last 30 days + 2. Review and update outdated content blocks + 3. Create weekly team update pages with consistent formatting + 4. Add status indicators and progress tracking to project pages + 5. Generate monthly documentation health reports + 6. Archive completed project pages and organize them in archive sections + """, + agent=doc_automator, + expected_output="Documentation automated with updated content, weekly reports, and organized archives" +) + +crew = Crew( + agents=[doc_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Permissão** +- Certifique-se de que sua conta Notion possui acesso de edição ao workspace desejado +- Verifique se a conexão OAuth inclui os escopos necessários para a API do Notion +- Confira se as páginas e bancos de dados estão compartilhados com a integração autenticada + +**IDs de Página e Bloco Inválidos** +- Revise os IDs de página e bloco para garantir que estejam no formato UUID correto +- Garanta que as páginas e blocos referenciados existem e são acessíveis +- Verifique se os IDs da página ou banco de dados pai são válidos ao criar novas páginas + +**Problemas com Schema de Propriedades** +- Assegure que as propriedades da página correspondem ao schema do banco de dados ao criar páginas em bancos de dados +- Verifique se os nomes e tipos das propriedades estão corretos para o banco de dados alvo +- Confirme que as propriedades obrigatórias estão incluídas ao criar ou atualizar páginas + +**Estrutura dos Blocos de Conteúdo** +- Assegure que o conteúdo dos blocos segue as especificações de rich text do Notion +- Verifique se estruturas aninhadas de blocos estão devidamente formatadas +- Confira se URLs de mídias são acessíveis e estão corretamente formatadas + +**Problemas de Pesquisa e Filtros** +- Certifique-se de que as queries de pesquisa estão devidamente formatadas e não estão vazias +- Use nomes de campos válidos em fórmulas de filtro: `query`, `filter.value`, `direction`, `page_size` +- Teste pesquisas simples antes de construir condições de filtro mais complexas + +**Relacionamentos Pai-Filho** +- Verifique se a página ou banco de dados pai existe antes de criar páginas filhas +- Assegure que existam permissões apropriadas para o container pai +- Confirme que os schemas do banco permitem definir as propriedades desejadas + +**Rich Text e Conteúdo de Mídia** +- Assegure que URLs para imagens externas, PDFs e bookmarks sejam acessíveis +- Verifique se a formatação rich text segue as especificações da API do Notion +- Confira se os tipos de linguagem nos blocos de código são suportados pelo Notion + +**Operações de Arquivamento e Exclusão** +- Entenda a diferença entre arquivar (reversível) e excluir (permanente) +- Certifique-se de ter permissões para arquivar ou excluir o conteúdo desejado +- Tenha cuidado com operações em massa que possam afetar múltiplas páginas ou blocos + +### Obtendo Ajuda + + + Entre em contato com nosso time de suporte para auxílio na configuração ou solução de problemas com a integração Notion. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/salesforce.mdx b/docs/pt-BR/enterprise/integrations/salesforce.mdx new file mode 100644 index 000000000..d6f0d04a4 --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/salesforce.mdx @@ -0,0 +1,632 @@ +--- +title: Integração com Salesforce +description: "Automação de vendas e CRM com integração Salesforce para CrewAI." +icon: "salesforce" +--- + +## Visão Geral + +Permita que seus agentes gerenciem relacionamentos com clientes, processos de vendas e dados através do Salesforce. Crie e atualize registros, gerencie leads e oportunidades, execute consultas SOQL e otimize seus fluxos de trabalho de CRM com automação potencializada por IA. + +## Pré-requisitos + +Antes de usar a integração Salesforce, certifique-se de que você possui: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa +- Uma conta Salesforce com permissões apropriadas +- Sua conta Salesforce conectada via a [página de Integrações](https://app.crewai.com/integrations) + +## Ferramentas Disponíveis + +### **Gerenciamento de Registros** + + + + **Descrição:** Crie um novo registro de Contato no Salesforce. + + **Parâmetros:** + - `FirstName` (string, opcional): Primeiro nome + - `LastName` (string, obrigatório): Sobrenome - Este campo é obrigatório + - `accountId` (string, opcional): ID da Conta - Conta à qual o contato pertence + - `Email` (string, opcional): Endereço de e-mail + - `Title` (string, opcional): Cargo do contato, como CEO ou Vice-presidente + - `Description` (string, opcional): Descrição do contato + - `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Contato + + + + **Descrição:** Crie um novo registro de Lead no Salesforce. + + **Parâmetros:** + - `FirstName` (string, opcional): Primeiro nome + - `LastName` (string, obrigatório): Sobrenome - Este campo é obrigatório + - `Company` (string, obrigatório): Empresa - Este campo é obrigatório + - `Email` (string, opcional): Endereço de e-mail + - `Phone` (string, opcional): Número de telefone + - `Website` (string, opcional): URL do site + - `Title` (string, opcional): Cargo do contato, como CEO ou Vice-presidente + - `Status` (string, opcional): Status do Lead - Use as Configurações de Workflow do Connect Portal para selecionar o status do Lead + - `Description` (string, opcional): Descrição do lead + - `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Lead + + + + **Descrição:** Crie um novo registro de Oportunidade no Salesforce. + + **Parâmetros:** + - `Name` (string, obrigatório): Nome da Oportunidade - Este campo é obrigatório + - `StageName` (string, opcional): Estágio da Oportunidade - Use as Configurações de Workflow do Connect Portal para selecionar o estágio + - `CloseDate` (string, opcional): Data de fechamento no formato YYYY-MM-DD - Padrão para 30 dias a partir da data atual + - `AccountId` (string, opcional): Conta à qual a Oportunidade pertence + - `Amount` (string, opcional): Valor total estimado da venda + - `Description` (string, opcional): Descrição da oportunidade + - `OwnerId` (string, opcional): Usuário Salesforce designado para esta Oportunidade + - `NextStep` (string, opcional): Descrição da próxima tarefa no fechamento da Oportunidade + - `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Oportunidade + + + + **Descrição:** Crie um novo registro de Tarefa no Salesforce. + + **Parâmetros:** + - `whatId` (string, opcional): Relacionado ao ID - ID da Conta ou Oportunidade relacionada à Tarefa + - `whoId` (string, opcional): ID do Nome - ID do Contato ou Lead relacionado à Tarefa + - `subject` (string, obrigatório): Assunto da tarefa + - `activityDate` (string, opcional): Data da Atividade no formato YYYY-MM-DD + - `description` (string, opcional): Descrição da tarefa + - `taskSubtype` (string, obrigatório): Subtipo da Tarefa - Opções: task, email, listEmail, call + - `Status` (string, opcional): Status - Opções: Not Started, In Progress, Completed + - `ownerId` (string, opcional): ID do responsável - Usuário Salesforce designado para a Tarefa + - `callDurationInSeconds` (string, opcional): Duração da chamada em segundos + - `isReminderSet` (boolean, opcional): Se o lembrete está definido + - `reminderDateTime` (string, opcional): Data/Hora do lembrete no formato ISO + - `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Tarefa + + + + **Descrição:** Crie um novo registro de Conta no Salesforce. + + **Parâmetros:** + - `Name` (string, obrigatório): Nome da Conta - Este campo é obrigatório + - `OwnerId` (string, opcional): Usuário Salesforce responsável por esta Conta + - `Website` (string, opcional): URL do site + - `Phone` (string, opcional): Número de telefone + - `Description` (string, opcional): Descrição da conta + - `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Conta + + + + **Descrição:** Crie um registro de qualquer tipo de objeto no Salesforce. + + **Nota:** Esta é uma ferramenta flexível para criar registros de tipos de objetos personalizados ou desconhecidos. + + + +### **Atualização de Registros** + + + + **Descrição:** Atualize um registro de Contato existente no Salesforce. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do registro a ser atualizado + - `FirstName` (string, opcional): Primeiro nome + - `LastName` (string, opcional): Sobrenome + - `accountId` (string, opcional): ID da Conta à qual o contato pertence + - `Email` (string, opcional): Endereço de e-mail + - `Title` (string, opcional): Cargo do contato + - `Description` (string, opcional): Descrição do contato + - `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Contato + + + + **Descrição:** Atualize um registro de Lead existente no Salesforce. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do registro a ser atualizado + - `FirstName` (string, opcional): Primeiro nome + - `LastName` (string, opcional): Sobrenome + - `Company` (string, opcional): Nome da empresa + - `Email` (string, opcional): Endereço de e-mail + - `Phone` (string, opcional): Número de telefone + - `Website` (string, opcional): URL do site + - `Title` (string, opcional): Cargo do contato + - `Status` (string, opcional): Status do Lead + - `Description` (string, opcional): Descrição do lead + - `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Lead + + + + **Descrição:** Atualize um registro de Oportunidade existente no Salesforce. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do registro a ser atualizado + - `Name` (string, opcional): Nome da Oportunidade + - `StageName` (string, opcional): Estágio da oportunidade + - `CloseDate` (string, opcional): Data de fechamento no formato YYYY-MM-DD + - `AccountId` (string, opcional): Conta à qual a Oportunidade pertence + - `Amount` (string, opcional): Valor total estimado da venda + - `Description` (string, opcional): Descrição da oportunidade + - `OwnerId` (string, opcional): Usuário Salesforce responsável por esta Oportunidade + - `NextStep` (string, opcional): Descrição da próxima tarefa no fechamento da Oportunidade + - `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Oportunidade + + + + **Descrição:** Atualize um registro de Tarefa existente no Salesforce. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do registro a ser atualizado + - `whatId` (string, opcional): Relacionado ao ID - ID da Conta ou Oportunidade relacionada + - `whoId` (string, opcional): ID do Nome - ID do Contato ou Lead relacionado à Tarefa + - `subject` (string, opcional): Assunto da tarefa + - `activityDate` (string, opcional): Data da Atividade no formato YYYY-MM-DD + - `description` (string, opcional): Descrição da tarefa + - `Status` (string, opcional): Status - Opções: Not Started, In Progress, Completed + - `ownerId` (string, opcional): ID do responsável - Usuário Salesforce designado para a Tarefa + - `callDurationInSeconds` (string, opcional): Duração da chamada em segundos + - `isReminderSet` (boolean, opcional): Se o lembrete está definido + - `reminderDateTime` (string, opcional): Data/Hora do lembrete em formato ISO + - `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Tarefa + + + + **Descrição:** Atualize um registro de Conta existente no Salesforce. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do registro a ser atualizado + - `Name` (string, opcional): Nome da Conta + - `OwnerId` (string, opcional): Usuário Salesforce responsável por esta Conta + - `Website` (string, opcional): URL do site + - `Phone` (string, opcional): Número de telefone + - `Description` (string, opcional): Descrição da conta + - `additionalFields` (object, opcional): Campos adicionais no formato JSON para campos personalizados de Conta + + + + **Descrição:** Atualize um registro de qualquer tipo de objeto no Salesforce. + + **Nota:** Esta é uma ferramenta flexível para atualizar registros de tipos de objetos personalizados ou desconhecidos. + + + +### **Recuperação de Registros** + + + + **Descrição:** Obtenha um registro de Contato pelo seu ID. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do registro do Contato + + + + **Descrição:** Obtenha um registro de Lead pelo seu ID. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do registro do Lead + + + + **Descrição:** Obtenha um registro de Oportunidade pelo seu ID. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do registro da Oportunidade + + + + **Descrição:** Obtenha um registro de Tarefa pelo seu ID. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do registro da Tarefa + + + + **Descrição:** Obtenha um registro de Conta pelo seu ID. + + **Parâmetros:** + - `recordId` (string, obrigatório): ID do registro da Conta + + + + **Descrição:** Obtenha um registro de qualquer tipo de objeto pelo seu ID. + + **Parâmetros:** + - `recordType` (string, obrigatório): Tipo do registro (ex.: "CustomObject__c") + - `recordId` (string, obrigatório): ID do registro + + + +### **Busca de Registros** + + + + **Descrição:** Pesquise registros de Contato com filtragem avançada. + + **Parâmetros:** + - `filterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com operadores específicos de campo + - `sortBy` (string, opcional): Campo para ordenação (ex.: "CreatedDate") + - `sortDirection` (string, opcional): Direção da ordenação - Opções: ASC, DESC + - `includeAllFields` (boolean, opcional): Incluir todos os campos nos resultados + - `paginationParameters` (object, opcional): Configurações de paginação com pageCursor + + + + **Descrição:** Pesquise registros de Lead com filtragem avançada. + + **Parâmetros:** + - `filterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com operadores específicos de campo + - `sortBy` (string, opcional): Campo para ordenação (ex.: "CreatedDate") + - `sortDirection` (string, opcional): Direção da ordenação - Opções: ASC, DESC + - `includeAllFields` (boolean, opcional): Incluir todos os campos nos resultados + - `paginationParameters` (object, opcional): Configurações de paginação com pageCursor + + + + **Descrição:** Pesquise registros de Oportunidade com filtragem avançada. + + **Parâmetros:** + - `filterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com operadores específicos de campo + - `sortBy` (string, opcional): Campo para ordenação (ex.: "CreatedDate") + - `sortDirection` (string, opcional): Direção da ordenação - Opções: ASC, DESC + - `includeAllFields` (boolean, opcional): Incluir todos os campos nos resultados + - `paginationParameters` (object, opcional): Configurações de paginação com pageCursor + + + + **Descrição:** Pesquise registros de Tarefa com filtragem avançada. + + **Parâmetros:** + - `filterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com operadores específicos de campo + - `sortBy` (string, opcional): Campo para ordenação (ex.: "CreatedDate") + - `sortDirection` (string, opcional): Direção da ordenação - Opções: ASC, DESC + - `includeAllFields` (boolean, opcional): Incluir todos os campos nos resultados + - `paginationParameters` (object, opcional): Configurações de paginação com pageCursor + + + + **Descrição:** Pesquise registros de Conta com filtragem avançada. + + **Parâmetros:** + - `filterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com operadores específicos de campo + - `sortBy` (string, opcional): Campo para ordenação (ex.: "CreatedDate") + - `sortDirection` (string, opcional): Direção da ordenação - Opções: ASC, DESC + - `includeAllFields` (boolean, opcional): Incluir todos os campos nos resultados + - `paginationParameters` (object, opcional): Configurações de paginação com pageCursor + + + + **Descrição:** Pesquise registros de qualquer tipo de objeto. + + **Parâmetros:** + - `recordType` (string, obrigatório): Tipo de registro para buscar + - `filterFormula` (string, opcional): Critérios de busca por filtro + - `includeAllFields` (boolean, opcional): Incluir todos os campos nos resultados + - `paginationParameters` (object, opcional): Configurações de paginação com pageCursor + + + +### **Recuperação por List View** + + + + **Descrição:** Obtenha registros de Contato de um List View específico. + + **Parâmetros:** + - `listViewId` (string, obrigatório): ID do List View + - `paginationParameters` (object, opcional): Configurações de paginação com pageCursor + + + + **Descrição:** Obtenha registros de Lead de um List View específico. + + **Parâmetros:** + - `listViewId` (string, obrigatório): ID do List View + - `paginationParameters` (object, opcional): Configurações de paginação com pageCursor + + + + **Descrição:** Obtenha registros de Oportunidade de um List View específico. + + **Parâmetros:** + - `listViewId` (string, obrigatório): ID do List View + - `paginationParameters` (object, opcional): Configurações de paginação com pageCursor + + + + **Descrição:** Obtenha registros de Tarefa de um List View específico. + + **Parâmetros:** + - `listViewId` (string, obrigatório): ID do List View + - `paginationParameters` (object, opcional): Configurações de paginação com pageCursor + + + + **Descrição:** Obtenha registros de Conta de um List View específico. + + **Parâmetros:** + - `listViewId` (string, obrigatório): ID do List View + - `paginationParameters` (object, opcional): Configurações de paginação com pageCursor + + + + **Descrição:** Obtenha registros de qualquer tipo de objeto a partir de um List View específico. + + **Parâmetros:** + - `recordType` (string, obrigatório): Tipo do registro + - `listViewId` (string, obrigatório): ID do List View + - `paginationParameters` (object, opcional): Configurações de paginação com pageCursor + + + +### **Campos Personalizados** + + + + **Descrição:** Crie campos personalizados para objetos de Contato. + + **Parâmetros:** + - `label` (string, obrigatório): Rótulo do campo para exibições e referência interna + - `type` (string, obrigatório): Tipo do campo - Opções: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url + - `defaultCheckboxValue` (boolean, opcional): Valor padrão para campos checkbox + - `length` (string, obrigatório): Comprimento para campos numéricos/texto + - `decimalPlace` (string, obrigatório): Casas decimais para campos numéricos + - `pickListValues` (string, obrigatório): Valores para campos picklist (separados por novas linhas) + - `visibleLines` (string, obrigatório): Linhas visíveis para campos multiseleção/área de texto + - `description` (string, opcional): Descrição do campo + - `helperText` (string, opcional): Texto de ajuda exibido ao passar o mouse + - `defaultFieldValue` (string, opcional): Valor padrão do campo + + + + **Descrição:** Crie campos personalizados para objetos de Lead. + + **Parâmetros:** + - `label` (string, obrigatório): Rótulo do campo para exibições e referência interna + - `type` (string, obrigatório): Tipo do campo - Opções: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url + - `defaultCheckboxValue` (boolean, opcional): Valor padrão para campos checkbox + - `length` (string, obrigatório): Comprimento para campos numéricos/texto + - `decimalPlace` (string, obrigatório): Casas decimais para campos numéricos + - `pickListValues` (string, obrigatório): Valores para campos picklist (separados por novas linhas) + - `visibleLines` (string, obrigatório): Linhas visíveis para campos multiseleção/área de texto + - `description` (string, opcional): Descrição do campo + - `helperText` (string, opcional): Texto de ajuda exibido ao passar o mouse + - `defaultFieldValue` (string, opcional): Valor padrão do campo + + + + **Descrição:** Crie campos personalizados para objetos de Oportunidade. + + **Parâmetros:** + - `label` (string, obrigatório): Rótulo do campo para exibições e referência interna + - `type` (string, obrigatório): Tipo do campo - Opções: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url + - `defaultCheckboxValue` (boolean, opcional): Valor padrão para campos checkbox + - `length` (string, obrigatório): Comprimento para campos numéricos/texto + - `decimalPlace` (string, obrigatório): Casas decimais para campos numéricos + - `pickListValues` (string, obrigatório): Valores para campos picklist (separados por novas linhas) + - `visibleLines` (string, obrigatório): Linhas visíveis para campos multiseleção/área de texto + - `description` (string, opcional): Descrição do campo + - `helperText` (string, opcional): Texto de ajuda exibido ao passar o mouse + - `defaultFieldValue` (string, opcional): Valor padrão do campo + + + + **Descrição:** Crie campos personalizados para objetos de Tarefa. + + **Parâmetros:** + - `label` (string, obrigatório): Rótulo do campo para exibições e referência interna + - `type` (string, obrigatório): Tipo do campo - Opções: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, Time, Url + - `defaultCheckboxValue` (boolean, opcional): Valor padrão para campos checkbox + - `length` (string, obrigatório): Comprimento para campos numéricos/texto + - `decimalPlace` (string, obrigatório): Casas decimais para campos numéricos + - `pickListValues` (string, obrigatório): Valores para campos picklist (separados por novas linhas) + - `visibleLines` (string, obrigatório): Linhas visíveis para campos multiseleção + - `description` (string, opcional): Descrição do campo + - `helperText` (string, opcional): Texto de ajuda exibido ao passar o mouse + - `defaultFieldValue` (string, opcional): Valor padrão do campo + + + + **Descrição:** Crie campos personalizados para objetos de Conta. + + **Parâmetros:** + - `label` (string, obrigatório): Rótulo do campo para exibições e referência interna + - `type` (string, obrigatório): Tipo do campo - Opções: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url + - `defaultCheckboxValue` (boolean, opcional): Valor padrão para campos checkbox + - `length` (string, obrigatório): Comprimento para campos numéricos/texto + - `decimalPlace` (string, obrigatório): Casas decimais para campos numéricos + - `pickListValues` (string, obrigatório): Valores para campos picklist (separados por novas linhas) + - `visibleLines` (string, obrigatório): Linhas visíveis para campos multiseleção/área de texto + - `description` (string, opcional): Descrição do campo + - `helperText` (string, opcional): Texto de ajuda exibido ao passar o mouse + - `defaultFieldValue` (string, opcional): Valor padrão do campo + + + + **Descrição:** Crie campos personalizados para qualquer tipo de objeto. + + **Nota:** Esta é uma ferramenta flexível para criar campos personalizados para tipos de objetos personalizados ou desconhecidos. + + + +### **Operações Avançadas** + + + + **Descrição:** Execute consultas SOQL personalizadas em seus dados do Salesforce. + + **Parâmetros:** + - `query` (string, obrigatório): Consulta SOQL (ex.: "SELECT Id, Name FROM Account WHERE Name = 'Exemplo'") + + + + **Descrição:** Crie um novo objeto personalizado no Salesforce. + + **Parâmetros:** + - `label` (string, obrigatório): Rótulo do objeto para abas, layouts de página e relatórios + - `pluralLabel` (string, obrigatório): Rótulo plural (ex.: "Contas") + - `description` (string, opcional): Uma descrição do Objeto Personalizado + - `recordName` (string, obrigatório): Nome do registro exibido em layouts e buscas (ex.: "Nome da Conta") + + + + **Descrição:** Obtenha o schema esperado para operações em tipos de objetos específicos. + + **Parâmetros:** + - `recordType` (string, obrigatório): Tipo de registro a ser detalhado + - `operation` (string, obrigatório): Tipo de Operação (ex.: "CREATE_RECORD" ou "UPDATE_RECORD") + + **Nota:** Use esta função primeiro ao trabalhar com objetos personalizados para entender seu schema antes de realizar operações. + + + +## Exemplos de Uso + +### Configuração Básica de um Agente Salesforce + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Obtenha ferramentas enterprise (ferramentas Salesforce serão incluídas) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Crie um agente com capacidades Salesforce +salesforce_agent = Agent( + role="CRM Manager", + goal="Manage customer relationships and sales processes efficiently", + backstory="An AI assistant specialized in CRM operations and sales automation.", + tools=[enterprise_tools] +) + +# Task to create a new lead +create_lead_task = Task( + description="Create a new lead for John Doe from Example Corp with email john.doe@example.com", + agent=salesforce_agent, + expected_output="Lead created successfully with lead ID" +) + +# Run the task +crew = Crew( + agents=[salesforce_agent], + tasks=[create_lead_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Salesforce Específicas + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Obtenha apenas ferramentas Salesforce específicas +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["salesforce_create_record_lead", "salesforce_update_record_opportunity", "salesforce_search_records_contact"] +) + +sales_manager = Agent( + role="Sales Manager", + goal="Manage leads and opportunities in the sales pipeline", + backstory="An experienced sales manager who handles lead qualification and opportunity management.", + tools=enterprise_tools +) + +# Task to manage sales pipeline +pipeline_task = Task( + description="Create a qualified lead and convert it to an opportunity with $50,000 value", + agent=sales_manager, + expected_output="Lead created and opportunity established successfully" +) + +crew = Crew( + agents=[sales_manager], + tasks=[pipeline_task] +) + +crew.kickoff() +``` + +### Gerenciamento de Contatos e Contas + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +account_manager = Agent( + role="Account Manager", + goal="Manage customer accounts and maintain strong relationships", + backstory="An AI assistant that specializes in account management and customer relationship building.", + tools=[enterprise_tools] +) + +# Task to manage customer accounts +account_task = Task( + description=""" + 1. Create a new account for TechCorp Inc. + 2. Add John Doe as the primary contact for this account + 3. Create a follow-up task for next week to check on their project status + """, + agent=account_manager, + expected_output="Account, contact, and follow-up task created successfully" +) + +crew = Crew( + agents=[account_manager], + tasks=[account_task] +) + +crew.kickoff() +``` + +### Consultas SOQL Avançadas e Relatórios + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +data_analyst = Agent( + role="Sales Data Analyst", + goal="Generate insights from Salesforce data using SOQL queries", + backstory="An analytical AI that excels at extracting meaningful insights from CRM data.", + tools=[enterprise_tools] +) + +# Complex task involving SOQL queries and data analysis +analysis_task = Task( + description=""" + 1. Execute a SOQL query to find all opportunities closing this quarter + 2. Search for contacts at companies with opportunities over $100K + 3. Create a summary report of the sales pipeline status + 4. Update high-value opportunities with next steps + """, + agent=data_analyst, + expected_output="Comprehensive sales pipeline analysis with actionable insights" +) + +crew = Crew( + agents=[data_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +Esta documentação abrangente cobre todas as ferramentas Salesforce organizadas por funcionalidade, facilitando que os usuários encontrem as operações específicas de que necessitam para automação de seu CRM. + +### Precisa de ajuda? + + + Entre em contato com nossa equipe de suporte para assistência na configuração da integração com Salesforce ou para resolução de problemas. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/shopify.mdx b/docs/pt-BR/enterprise/integrations/shopify.mdx new file mode 100644 index 000000000..0d3b1ca7b --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/shopify.mdx @@ -0,0 +1,382 @@ +--- +title: Integração com Shopify +description: "Gestão de e-commerce e loja online com integração do Shopify para CrewAI." +icon: "shopify" +--- + +## Visão Geral + +Permita que seus agentes gerenciem operações de e-commerce através do Shopify. Gerencie clientes, pedidos, produtos, inventário e análises da loja para otimizar sua empresa online com automação alimentada por IA. + +## Pré-requisitos + +Antes de utilizar a integração com o Shopify, certifique-se de que você possui: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com uma assinatura ativa +- Uma loja Shopify com permissões administrativas adequadas +- Sua loja Shopify conectada através da [página de Integrações](https://app.crewai.com/integrations) + +## Ferramentas Disponíveis + +### **Gerenciamento de Clientes** + + + + **Descrição:** Recupera uma lista de clientes da sua loja Shopify. + + **Parâmetros:** + - `customerIds` (string, opcional): Lista de IDs de clientes separada por vírgula para filtrar (exemplo: "207119551, 207119552") + - `createdAtMin` (string, opcional): Retorna somente clientes criados após esta data (ISO ou timestamp Unix) + - `createdAtMax` (string, opcional): Retorna somente clientes criados antes desta data (ISO ou timestamp Unix) + - `updatedAtMin` (string, opcional): Retorna somente clientes atualizados após esta data (ISO ou timestamp Unix) + - `updatedAtMax` (string, opcional): Retorna somente clientes atualizados antes desta data (ISO ou timestamp Unix) + - `limit` (string, opcional): Número máximo de clientes a retornar (padrão 250) + + + + **Descrição:** Pesquise por clientes usando critérios de filtragem avançados. + + **Parâmetros:** + - `filterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com operadores específicos de campo + - `limit` (string, opcional): Número máximo de clientes a retornar (padrão 250) + + + + **Descrição:** Crie um novo cliente em sua loja Shopify. + + **Parâmetros:** + - `firstName` (string, obrigatório): Primeiro nome do cliente + - `lastName` (string, obrigatório): Sobrenome do cliente + - `email` (string, obrigatório): Endereço de e-mail do cliente + - `company` (string, opcional): Nome da empresa + - `streetAddressLine1` (string, opcional): Endereço + - `streetAddressLine2` (string, opcional): Complemento do endereço + - `city` (string, opcional): Cidade + - `state` (string, opcional): Estado ou código da província + - `country` (string, opcional): País + - `zipCode` (string, opcional): CEP + - `phone` (string, opcional): Telefone + - `tags` (string, opcional): Tags como array ou lista separada por vírgula + - `note` (string, opcional): Observação sobre o cliente + - `sendEmailInvite` (boolean, opcional): Se deve enviar convite por e-mail + - `metafields` (object, opcional): Metacampos adicionais em formato JSON + + + + **Descrição:** Atualize um cliente existente em sua loja Shopify. + + **Parâmetros:** + - `customerId` (string, obrigatório): O ID do cliente a ser atualizado + - `firstName` (string, opcional): Primeiro nome do cliente + - `lastName` (string, opcional): Sobrenome do cliente + - `email` (string, opcional): Endereço de e-mail do cliente + - `company` (string, opcional): Nome da empresa + - `streetAddressLine1` (string, opcional): Endereço + - `streetAddressLine2` (string, opcional): Complemento do endereço + - `city` (string, opcional): Cidade + - `state` (string, opcional): Estado ou código da província + - `country` (string, opcional): País + - `zipCode` (string, opcional): CEP + - `phone` (string, opcional): Telefone + - `tags` (string, opcional): Tags como array ou lista separada por vírgula + - `note` (string, opcional): Observação sobre o cliente + - `sendEmailInvite` (boolean, opcional): Se deve enviar convite por e-mail + - `metafields` (object, opcional): Metacampos adicionais em formato JSON + + + +### **Gestão de Pedidos** + + + + **Descrição:** Recupera uma lista de pedidos da sua loja Shopify. + + **Parâmetros:** + - `orderIds` (string, opcional): Lista de IDs de pedidos separada por vírgula para filtrar (exemplo: "450789469, 450789470") + - `createdAtMin` (string, opcional): Retorna somente pedidos criados após esta data (ISO ou timestamp Unix) + - `createdAtMax` (string, opcional): Retorna somente pedidos criados antes desta data (ISO ou timestamp Unix) + - `updatedAtMin` (string, opcional): Retorna somente pedidos atualizados após esta data (ISO ou timestamp Unix) + - `updatedAtMax` (string, opcional): Retorna somente pedidos atualizados antes desta data (ISO ou timestamp Unix) + - `limit` (string, opcional): Número máximo de pedidos a retornar (padrão 250) + + + + **Descrição:** Crie um novo pedido em sua loja Shopify. + + **Parâmetros:** + - `email` (string, obrigatório): Endereço de e-mail do cliente + - `lineItems` (object, obrigatório): Itens do pedido em formato JSON com título, preço, quantidade e variant_id + - `sendReceipt` (boolean, opcional): Se deve enviar recibo do pedido + - `fulfillmentStatus` (string, opcional): Status de atendimento - Opções: fulfilled, null, partial, restocked + - `financialStatus` (string, opcional): Status financeiro - Opções: pending, authorized, partially_paid, paid, partially_refunded, refunded, voided + - `inventoryBehaviour` (string, opcional): Comportamento de inventário - Opções: bypass, decrement_ignoring_policy, decrement_obeying_policy + - `note` (string, opcional): Observação do pedido + + + + **Descrição:** Atualize um pedido existente em sua loja Shopify. + + **Parâmetros:** + - `orderId` (string, obrigatório): O ID do pedido a ser atualizado + - `email` (string, opcional): Endereço de e-mail do cliente + - `lineItems` (object, opcional): Itens do pedido atualizados em formato JSON + - `sendReceipt` (boolean, opcional): Se deve enviar recibo do pedido + - `fulfillmentStatus` (string, opcional): Status de atendimento - Opções: fulfilled, null, partial, restocked + - `financialStatus` (string, opcional): Status financeiro - Opções: pending, authorized, partially_paid, paid, partially_refunded, refunded, voided + - `inventoryBehaviour` (string, opcional): Comportamento de inventário - Opções: bypass, decrement_ignoring_policy, decrement_obeying_policy + - `note` (string, opcional): Observação do pedido + + + + **Descrição:** Recupera carrinhos abandonados da sua loja Shopify. + + **Parâmetros:** + - `createdWithInLast` (string, opcional): Restringe os resultados para checkouts criados dentro do período especificado + - `createdAfterId` (string, opcional): Restringe os resultados após o ID especificado + - `status` (string, opcional): Mostra checkouts com o status especificado - Opções: open, closed (padrão open) + - `createdAtMin` (string, opcional): Retorna somente carrinhos criados após esta data (ISO ou timestamp Unix) + - `createdAtMax` (string, opcional): Retorna somente carrinhos criados antes desta data (ISO ou timestamp Unix) + - `limit` (string, opcional): Número máximo de carrinhos a retornar (padrão 250) + + + +### **Gestão de Produtos (REST API)** + + + + **Descrição:** Recupera uma lista de produtos da sua loja Shopify utilizando a REST API. + + **Parâmetros:** + - `productIds` (string, opcional): Lista de IDs de produtos separada por vírgula para filtrar (exemplo: "632910392, 632910393") + - `title` (string, opcional): Filtrar pelo título do produto + - `productType` (string, opcional): Filtrar pelo tipo de produto + - `vendor` (string, opcional): Filtrar por fornecedor + - `status` (string, opcional): Filtrar por status - Opções: active, archived, draft + - `createdAtMin` (string, opcional): Retorna somente produtos criados após esta data (ISO ou timestamp Unix) + - `createdAtMax` (string, opcional): Retorna somente produtos criados antes desta data (ISO ou timestamp Unix) + - `updatedAtMin` (string, opcional): Retorna somente produtos atualizados após esta data (ISO ou timestamp Unix) + - `updatedAtMax` (string, opcional): Retorna somente produtos atualizados antes desta data (ISO ou timestamp Unix) + - `limit` (string, opcional): Número máximo de produtos a retornar (padrão 250) + + + + **Descrição:** Crie um novo produto em sua loja Shopify utilizando a REST API. + + **Parâmetros:** + - `title` (string, obrigatório): Título do produto + - `productType` (string, obrigatório): Tipo/categoria do produto + - `vendor` (string, obrigatório): Fornecedor do produto + - `productDescription` (string, opcional): Descrição do produto (aceita texto simples ou HTML) + - `tags` (string, opcional): Tags do produto como array ou lista separada por vírgula + - `price` (string, opcional): Preço do produto + - `inventoryPolicy` (string, opcional): Política de estoque - Opções: deny, continue + - `imageUrl` (string, opcional): URL da imagem do produto + - `isPublished` (boolean, opcional): Se o produto está publicado + - `publishToPointToSale` (boolean, opcional): Se deve publicar no ponto de venda + + + + **Descrição:** Atualize um produto existente em sua loja Shopify utilizando a REST API. + + **Parâmetros:** + - `productId` (string, obrigatório): O ID do produto a ser atualizado + - `title` (string, opcional): Título do produto + - `productType` (string, opcional): Tipo/categoria do produto + - `vendor` (string, opcional): Fornecedor do produto + - `productDescription` (string, opcional): Descrição do produto (aceita texto simples ou HTML) + - `tags` (string, opcional): Tags do produto como array ou lista separada por vírgula + - `price` (string, opcional): Preço do produto + - `inventoryPolicy` (string, opcional): Política de estoque - Opções: deny, continue + - `imageUrl` (string, opcional): URL da imagem do produto + - `isPublished` (boolean, opcional): Se o produto está publicado + - `publishToPointToSale` (boolean, opcional): Se deve publicar no ponto de venda + + + +### **Gestão de Produtos (GraphQL)** + + + + **Descrição:** Recupere produtos utilizando filtros avançados do GraphQL. + + **Parâmetros:** + - `productFilterFormula` (object, opcional): Filtro avançado em forma normal disjuntiva com suporte a campos como id, title, vendor, status, handle, tag, created_at, updated_at, published_at + + + + **Descrição:** Crie um novo produto utilizando a API GraphQL com suporte aprimorado a mídias. + + **Parâmetros:** + - `title` (string, obrigatório): Título do produto + - `productType` (string, obrigatório): Tipo/categoria do produto + - `vendor` (string, obrigatório): Fornecedor do produto + - `productDescription` (string, opcional): Descrição do produto (aceita texto simples ou HTML) + - `tags` (string, opcional): Tags do produto como array ou lista separada por vírgula + - `media` (object, opcional): Objetos de mídia com texto alternativo, tipo de conteúdo e URL de origem + - `additionalFields` (object, opcional): Campos adicionais do produto como status, requiresSellingPlan, giftCard + + + + **Descrição:** Atualize um produto existente utilizando a API GraphQL com suporte aprimorado a mídias. + + **Parâmetros:** + - `productId` (string, obrigatório): O ID GraphQL do produto a ser atualizado (ex.: "gid://shopify/Product/913144112") + - `title` (string, opcional): Título do produto + - `productType` (string, opcional): Tipo/categoria do produto + - `vendor` (string, opcional): Fornecedor do produto + - `productDescription` (string, opcional): Descrição do produto (aceita texto simples ou HTML) + - `tags` (string, opcional): Tags do produto como array ou lista separada por vírgula + - `media` (object, opcional): Objetos de mídia atualizados com texto alternativo, tipo de conteúdo e URL de origem + - `additionalFields` (object, opcional): Campos adicionais do produto como status, requiresSellingPlan, giftCard + + + +## Exemplos de Uso + +### Configuração Básica do Agente Shopify + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Get enterprise tools (Shopify tools will be included) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Create an agent with Shopify capabilities +shopify_agent = Agent( + role="E-commerce Manager", + goal="Manage online store operations and customer relationships efficiently", + backstory="An AI assistant specialized in e-commerce operations and online store management.", + tools=[enterprise_tools] +) + +# Task to create a new customer +create_customer_task = Task( + description="Create a new VIP customer Jane Smith with email jane.smith@example.com and phone +1-555-0123", + agent=shopify_agent, + expected_output="Customer created successfully with customer ID" +) + +# Run the task +crew = Crew( + agents=[shopify_agent], + tasks=[create_customer_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Shopify + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Get only specific Shopify tools +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["shopify_create_customer", "shopify_create_order", "shopify_get_products"] +) + +store_manager = Agent( + role="Store Manager", + goal="Manage customer orders and product catalog", + backstory="An experienced store manager who handles customer relationships and inventory management.", + tools=enterprise_tools +) + +# Task to manage store operations +store_task = Task( + description="Create a new customer and process their order for 2 Premium Coffee Mugs", + agent=store_manager, + expected_output="Customer created and order processed successfully" +) + +crew = Crew( + agents=[store_manager], + tasks=[store_task] +) + +crew.kickoff() +``` + +### Gestão de Produtos com GraphQL + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +product_manager = Agent( + role="Product Manager", + goal="Manage product catalog and inventory with advanced GraphQL capabilities", + backstory="An AI assistant that specializes in product management and catalog optimization.", + tools=[enterprise_tools] +) + +# Task to manage product catalog +catalog_task = Task( + description=""" + 1. Create a new product "Premium Coffee Mug" from Coffee Co vendor + 2. Add high-quality product images and descriptions + 3. Search for similar products from the same vendor + 4. Update product tags and pricing strategy + """, + agent=product_manager, + expected_output="Product created and catalog optimized successfully" +) + +crew = Crew( + agents=[product_manager], + tasks=[catalog_task] +) + +crew.kickoff() +``` + +### Análise de Pedidos e Clientes + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +analytics_agent = Agent( + role="E-commerce Analyst", + goal="Analyze customer behavior and order patterns to optimize store performance", + backstory="An analytical AI that excels at extracting insights from e-commerce data.", + tools=[enterprise_tools] +) + +# Complex task involving multiple operations +analytics_task = Task( + description=""" + 1. Retrieve recent customer data and order history + 2. Identify abandoned carts from the last 7 days + 3. Analyze product performance and inventory levels + 4. Generate recommendations for customer retention + """, + agent=analytics_agent, + expected_output="Comprehensive e-commerce analytics report with actionable insights" +) + +crew = Crew( + agents=[analytics_agent], + tasks=[analytics_task] +) + +crew.kickoff() +``` + +### Precisa de Ajuda? + + + Entre em contato com nossa equipe de suporte para assistência na configuração ou resolução de problemas de integração com o Shopify. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/slack.mdx b/docs/pt-BR/enterprise/integrations/slack.mdx new file mode 100644 index 000000000..63c7224da --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/slack.mdx @@ -0,0 +1,293 @@ +--- +title: Integração com Slack +description: "Comunicação e colaboração em equipe com a integração Slack para CrewAI." +icon: "slack" +--- + +## Visão Geral + +Permita que seus agentes gerenciem a comunicação da equipe pelo Slack. Envie mensagens, pesquise conversas, gerencie canais e coordene as atividades do time para otimizar os fluxos de colaboração com automação impulsionada por IA. + +## Pré-requisitos + +Antes de usar a integração com o Slack, certifique-se de que você tenha: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com assinatura ativa +- Um workspace do Slack com permissões apropriadas +- Seu workspace do Slack conectado por meio da [página de Integrações](https://app.crewai.com/integrations) + +## Ferramentas Disponíveis + +### **Gerenciamento de Usuários** + + + + **Descrição:** Lista todos os membros de um canal do Slack. + + **Parâmetros:** + - Nenhum parâmetro necessário – recupera todos os membros do canal + + + + **Descrição:** Encontre um usuário no seu workspace do Slack pelo endereço de e-mail. + + **Parâmetros:** + - `email` (string, obrigatório): O endereço de e-mail de um usuário do workspace + + + + **Descrição:** Pesquise usuários pelo nome ou nome de exibição. + + **Parâmetros:** + - `name` (string, obrigatório): Nome real do usuário para a pesquisa + - `displayName` (string, obrigatório): Nome de exibição do usuário para a pesquisa + - `paginationParameters` (object, opcional): Configurações de paginação + - `pageCursor` (string, opcional): Cursor de página para paginação + + + +### **Gerenciamento de Canais** + + + + **Descrição:** Lista todos os canais do seu workspace no Slack. + + **Parâmetros:** + - Nenhum parâmetro necessário – recupera todos os canais acessíveis + + + +### **Mensagens** + + + + **Descrição:** Envie uma mensagem para um canal do Slack. + + **Parâmetros:** + - `channel` (string, obrigatório): Nome ou ID do canal – Use as Configurações de Workflow do Connect Portal para que usuários selecionem o canal, ou insira o nome do canal para criar um novo + - `message` (string, obrigatório): Texto da mensagem a ser enviada + - `botName` (string, obrigatório): Nome do bot que enviará a mensagem + - `botIcon` (string, obrigatório): Ícone do bot – Pode ser uma URL de imagem ou um emoji (ex.: ":dog:") + - `blocks` (object, opcional): JSON do Slack Block Kit para mensagens ricas com anexos e elementos interativos + - `authenticatedUser` (boolean, opcional): Se verdadeiro, a mensagem aparecerá como enviada pelo seu usuário autenticado do Slack ao invés do aplicativo (por padrão é falso) + + + + **Descrição:** Envie uma mensagem direta para um usuário específico no Slack. + + **Parâmetros:** + - `memberId` (string, obrigatório): ID do usuário destinatário – Use as Configurações de Workflow do Connect Portal para que usuários selecionem um membro + - `message` (string, obrigatório): Texto da mensagem a ser enviada + - `botName` (string, obrigatório): Nome do bot que enviará a mensagem + - `botIcon` (string, obrigatório): Ícone do bot – Pode ser uma URL de imagem ou um emoji (ex.: ":dog:") + - `blocks` (object, opcional): JSON do Slack Block Kit para formatação rica com anexos e elementos interativos + - `authenticatedUser` (boolean, opcional): Se verdadeiro, a mensagem aparecerá como enviada pelo seu usuário autenticado do Slack (padrão é falso) + + + +### **Pesquisa & Descoberta** + + + + **Descrição:** Procure por mensagens em todo o seu workspace do Slack. + + **Parâmetros:** + - `query` (string, obrigatório): Consulta de pesquisa usando a sintaxe do Slack para encontrar mensagens que correspondam aos critérios especificados + + **Exemplos de Consultas de Pesquisa:** + - `"project update"` – Busca mensagens contendo "project update" + - `from:@john in:#general` – Busca mensagens do John no canal #general + - `has:link after:2023-01-01` – Busca mensagens com links após 1º de janeiro de 2023 + - `in:@channel before:yesterday` – Busca mensagens em um canal específico antes de ontem + + + +## Integração com Block Kit + +O Block Kit do Slack permite criar mensagens ricas e interativas. Veja alguns exemplos de como usar o parâmetro `blocks`: + +### Texto Simples com Anexo +```json +[ + { + "text": "I am a test message", + "attachments": [ + { + "text": "And here's an attachment!" + } + ] + } +] +``` + +### Formatação Rica com Seções +```json +[ + { + "type": "section", + "text": { + "type": "mrkdwn", + "text": "*Project Update*\nStatus: ✅ Complete" + } + }, + { + "type": "divider" + }, + { + "type": "section", + "text": { + "type": "plain_text", + "text": "All tasks have been completed successfully." + } + } +] +``` + +## Exemplos de Uso + +### Configuração Básica de Agente Slack + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Get enterprise tools (Slack tools will be included) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Create an agent with Slack capabilities +slack_agent = Agent( + role="Team Communication Manager", + goal="Facilitate team communication and coordinate collaboration efficiently", + backstory="An AI assistant specialized in team communication and workspace coordination.", + tools=[enterprise_tools] +) + +# Task to send project updates +update_task = Task( + description="Send a project status update to the #general channel with current progress", + agent=slack_agent, + expected_output="Project update message sent successfully to team channel" +) + +# Run the task +crew = Crew( + agents=[slack_agent], + tasks=[update_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Slack + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Get only specific Slack tools +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["slack_send_message", "slack_send_direct_message", "slack_search_messages"] +) + +communication_manager = Agent( + role="Communication Coordinator", + goal="Manage team communications and ensure important messages reach the right people", + backstory="An experienced communication coordinator who handles team messaging and notifications.", + tools=enterprise_tools +) + +# Task to coordinate team communication +coordination_task = Task( + description="Send task completion notifications to team members and update project channels", + agent=communication_manager, + expected_output="Team notifications sent and project channels updated successfully" +) + +crew = Crew( + agents=[communication_manager], + tasks=[coordination_task] +) + +crew.kickoff() +``` + +### Mensagens Avançadas com Block Kit + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +notification_agent = Agent( + role="Notification Manager", + goal="Create rich, interactive notifications and manage workspace communication", + backstory="An AI assistant that specializes in creating engaging team notifications and updates.", + tools=[enterprise_tools] +) + +# Task to send rich notifications +notification_task = Task( + description=""" + 1. Send a formatted project completion message to #general with progress charts + 2. Send direct messages to team leads with task summaries + 3. Create interactive notification with action buttons for team feedback + """, + agent=notification_agent, + expected_output="Rich notifications sent with interactive elements and formatted content" +) + +crew = Crew( + agents=[notification_agent], + tasks=[notification_task] +) + +crew.kickoff() +``` + +### Pesquisa de Mensagens e Análises + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +analytics_agent = Agent( + role="Communication Analyst", + goal="Analyze team communication patterns and extract insights from conversations", + backstory="An analytical AI that excels at understanding team dynamics through communication data.", + tools=[enterprise_tools] +) + +# Complex task involving search and analysis +analysis_task = Task( + description=""" + 1. Search for recent project-related messages across all channels + 2. Find users by email to identify team members + 3. Analyze communication patterns and response times + 4. Generate weekly team communication summary + """, + agent=analytics_agent, + expected_output="Comprehensive communication analysis with team insights and recommendations" +) + +crew = Crew( + agents=[analytics_agent], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +## Fale com o Suporte + + + Entre em contato com nossa equipe de suporte para obter ajuda na configuração ou solução de problemas da integração com o Slack. + \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/stripe.mdx b/docs/pt-BR/enterprise/integrations/stripe.mdx new file mode 100644 index 000000000..96bb2b596 --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/stripe.mdx @@ -0,0 +1,305 @@ +--- +title: Integração Stripe +description: "Processamento de pagamentos e gerenciamento de assinaturas com integração Stripe para CrewAI." +icon: "stripe" +--- + +## Visão Geral + +Permita que seus agentes gerenciem pagamentos, assinaturas e faturamento de clientes através do Stripe. Gerencie dados de clientes, processe assinaturas, gerencie produtos e acompanhe transações financeiras para otimizar seus fluxos de pagamento com automação impulsionada por IA. + +## Pré-requisitos + +Antes de usar a integração com o Stripe, certifique-se de que você tem: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com uma assinatura ativa +- Uma conta Stripe com permissões apropriadas de API +- Sua conta Stripe conectada através da [página de Integrações](https://app.crewai.com/integrations) + +## Ferramentas Disponíveis + +### **Gerenciamento de Clientes** + + + + **Descrição:** Crie um novo cliente em sua conta Stripe. + + **Parâmetros:** + - `emailCreateCustomer` (string, obrigatório): Endereço de e-mail do cliente + - `name` (string, opcional): Nome completo do cliente + - `description` (string, opcional): Descrição do cliente para referência interna + - `metadataCreateCustomer` (objeto, opcional): Metadados adicionais como pares chave-valor (exemplo: `{"field1": 1, "field2": 2}`) + + + + **Descrição:** Recupera um cliente específico pelo ID do cliente Stripe. + + **Parâmetros:** + - `idGetCustomer` (string, obrigatório): O ID do cliente Stripe a ser recuperado + + + + **Descrição:** Recupera uma lista de clientes com filtragem opcional. + + **Parâmetros:** + - `emailGetCustomers` (string, opcional): Filtra clientes pelo endereço de e-mail + - `createdAfter` (string, opcional): Filtra clientes criados após esta data (timestamp Unix) + - `createdBefore` (string, opcional): Filtra clientes criados antes desta data (timestamp Unix) + - `limitGetCustomers` (string, opcional): Número máximo de clientes a retornar (padrão: 10) + + + + **Descrição:** Atualiza as informações de um cliente existente. + + **Parâmetros:** + - `customerId` (string, obrigatório): O ID do cliente a ser atualizado + - `emailUpdateCustomer` (string, opcional): Novo endereço de e-mail + - `name` (string, opcional): Novo nome do cliente + - `description` (string, opcional): Nova descrição do cliente + - `metadataUpdateCustomer` (objeto, opcional): Novos metadados como pares chave-valor + + + +### **Gerenciamento de Assinaturas** + + + + **Descrição:** Cria uma nova assinatura para um cliente. + + **Parâmetros:** + - `customerIdCreateSubscription` (string, obrigatório): O ID do cliente para o qual a assinatura será criada + - `plan` (string, obrigatório): O ID do plano para assinatura - Use as Configurações do Workflow do Portal Connect para permitir que usuários selecionem um plano + - `metadataCreateSubscription` (objeto, opcional): Metadados adicionais para a assinatura + + + + **Descrição:** Recupera assinaturas com filtragem opcional. + + **Parâmetros:** + - `customerIdGetSubscriptions` (string, opcional): Filtra assinaturas por ID do cliente + - `subscriptionStatus` (string, opcional): Filtra por status da assinatura - Opções: incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid + - `limitGetSubscriptions` (string, opcional): Número máximo de assinaturas a retornar (padrão: 10) + + + +### **Gerenciamento de Produtos** + + + + **Descrição:** Cria um novo produto no seu catálogo Stripe. + + **Parâmetros:** + - `productName` (string, obrigatório): Nome do produto + - `description` (string, opcional): Descrição do produto + - `metadataProduct` (objeto, opcional): Metadados adicionais do produto como pares chave-valor + + + + **Descrição:** Recupera um produto específico pelo ID do produto Stripe. + + **Parâmetros:** + - `productId` (string, obrigatório): O ID do produto Stripe a ser recuperado + + + + **Descrição:** Recupera uma lista de produtos com filtragem opcional. + + **Parâmetros:** + - `createdAfter` (string, opcional): Filtra produtos criados após esta data (timestamp Unix) + - `createdBefore` (string, opcional): Filtra produtos criados antes desta data (timestamp Unix) + - `limitGetProducts` (string, opcional): Número máximo de produtos a retornar (padrão: 10) + + + +### **Operações Financeiras** + + + + **Descrição:** Recupera transações de saldo da sua conta Stripe. + + **Parâmetros:** + - `balanceTransactionType` (string, opcional): Filtra por tipo de transação - Opções: charge, refund, payment, payment_refund + - `paginationParameters` (objeto, opcional): Configurações de paginação + - `pageCursor` (string, opcional): Cursor da página para paginação + + + + **Descrição:** Recupera planos de assinatura da sua conta Stripe. + + **Parâmetros:** + - `isPlanActive` (boolean, opcional): Filtra por status do plano - true para planos ativos, false para inativos + - `paginationParameters` (objeto, opcional): Configurações de paginação + - `pageCursor` (string, opcional): Cursor da página para paginação + + + +## Exemplos de Uso + +### Configuração Básica do Agente Stripe + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Get enterprise tools (Stripe tools will be included) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Create an agent with Stripe capabilities +stripe_agent = Agent( + role="Payment Manager", + goal="Manage customer payments, subscriptions, and billing operations efficiently", + backstory="An AI assistant specialized in payment processing and subscription management.", + tools=[enterprise_tools] +) + +# Task to create a new customer +create_customer_task = Task( + description="Create a new premium customer John Doe with email john.doe@example.com", + agent=stripe_agent, + expected_output="Customer created successfully with customer ID" +) + +# Run the task +crew = Crew( + agents=[stripe_agent], + tasks=[create_customer_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Stripe Específicas + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Get only specific Stripe tools +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["stripe_create_customer", "stripe_create_subscription", "stripe_get_balance_transactions"] +) + +billing_manager = Agent( + role="Billing Manager", + goal="Handle customer billing, subscriptions, and payment processing", + backstory="An experienced billing manager who handles subscription lifecycle and payment operations.", + tools=enterprise_tools +) + +# Task to manage billing operations +billing_task = Task( + description="Create a new customer and set up their premium subscription plan", + agent=billing_manager, + expected_output="Customer created and subscription activated successfully" +) + +crew = Crew( + agents=[billing_manager], + tasks=[billing_task] +) + +crew.kickoff() +``` + +### Gerenciamento de Assinaturas + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +subscription_manager = Agent( + role="Subscription Manager", + goal="Manage customer subscriptions and optimize recurring revenue", + backstory="An AI assistant that specializes in subscription lifecycle management and customer retention.", + tools=[enterprise_tools] +) + +# Task to manage subscription operations +subscription_task = Task( + description=""" + 1. Create a new product "Premium Service Plan" with advanced features + 2. Set up subscription plans with different tiers + 3. Create customers and assign them to appropriate plans + 4. Monitor subscription status and handle billing issues + """, + agent=subscription_manager, + expected_output="Subscription management system configured with customers and active plans" +) + +crew = Crew( + agents=[subscription_manager], + tasks=[subscription_task] +) + +crew.kickoff() +``` + +### Análises e Relatórios Financeiros + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +financial_analyst = Agent( + role="Financial Analyst", + goal="Analyze payment data and generate financial insights", + backstory="An analytical AI that excels at extracting insights from payment and subscription data.", + tools=[enterprise_tools] +) + +# Complex task involving financial analysis +analytics_task = Task( + description=""" + 1. Retrieve balance transactions for the current month + 2. Analyze customer payment patterns and subscription trends + 3. Identify high-value customers and subscription performance + 4. Generate monthly financial performance report + """, + agent=financial_analyst, + expected_output="Comprehensive financial analysis with payment insights and recommendations" +) + +crew = Crew( + agents=[financial_analyst], + tasks=[analytics_task] +) + +crew.kickoff() +``` + +## Referência de Status de Assinatura + +Compreendendo os status de assinaturas: + +- **incomplete** - A assinatura requer método de pagamento ou confirmação de pagamento +- **incomplete_expired** - A assinatura expirou antes da confirmação do pagamento +- **trialing** - A assinatura está em período de avaliação +- **active** - A assinatura está ativa e em dia +- **past_due** - O pagamento falhou mas a assinatura ainda está ativa +- **canceled** - A assinatura foi cancelada +- **unpaid** - O pagamento falhou e a assinatura não está mais ativa + +## Uso de Metadados + +Os metadados permitem que você armazene informações adicionais sobre clientes, assinaturas e produtos: + +```json +{ + "customer_segment": "enterprise", + "acquisition_source": "google_ads", + "lifetime_value": "high", + "custom_field_1": "value1" +} +``` + +Esta integração permite uma automação abrangente do gerenciamento de pagamentos e assinaturas, possibilitando que seus agentes de IA administrem operações de faturamento perfeitamente dentro do seu ecossistema Stripe. \ No newline at end of file diff --git a/docs/pt-BR/enterprise/integrations/zendesk.mdx b/docs/pt-BR/enterprise/integrations/zendesk.mdx new file mode 100644 index 000000000..c2fc19373 --- /dev/null +++ b/docs/pt-BR/enterprise/integrations/zendesk.mdx @@ -0,0 +1,343 @@ +--- +title: Integração com Zendesk +description: "Gestão de suporte ao cliente e helpdesk com integração Zendesk para CrewAI." +icon: "headset" +--- + +## Visão Geral + +Permita que seus agentes gerenciem operações de suporte ao cliente através do Zendesk. Crie e atualize tickets, gerencie usuários, monitore métricas de suporte e otimize seus fluxos de atendimento ao cliente com automação impulsionada por IA. + +## Pré-requisitos + +Antes de usar a integração com o Zendesk, certifique-se de que você possui: + +- Uma conta [CrewAI Enterprise](https://app.crewai.com) com uma assinatura ativa +- Uma conta Zendesk com permissões apropriadas de API +- Sua conta Zendesk conectada através da [página de Integrações](https://app.crewai.com/integrations) + +## Ferramentas Disponíveis + +### **Gerenciamento de Tickets** + + + + **Descrição:** Crie um novo ticket de suporte no Zendesk. + + **Parâmetros:** + - `ticketSubject` (string, obrigatório): Assunto do ticket (ex.: "Socorro, minha impressora está pegando fogo!") + - `ticketDescription` (string, obrigatório): Primeiro comentário que aparece no ticket (ex.: "A fumaça é muito colorida.") + - `requesterName` (string, obrigatório): Nome do usuário solicitando suporte (ex.: "Jane Cliente") + - `requesterEmail` (string, obrigatório): E-mail do solicitante do suporte (ex.: "jane@example.com") + - `assigneeId` (string, opcional): ID do agente Zendesk atribuído ao ticket - Use as Configurações de Fluxo de Trabalho do Portal Connect para permitir a seleção do responsável + - `ticketType` (string, opcional): Tipo de ticket - Opções: problem, incident, question, task + - `ticketPriority` (string, opcional): Nível de prioridade - Opções: urgent, high, normal, low + - `ticketStatus` (string, opcional): Status do ticket - Opções: new, open, pending, hold, solved, closed + - `ticketDueAt` (string, opcional): Data de vencimento para tickets do tipo tarefa (timestamp ISO 8601) + - `ticketTags` (string, opcional): Array de tags a aplicar (ex.: `["enterprise", "outra_tag"]`) + - `ticketExternalId` (string, opcional): ID externo para vincular tickets a registros locais + - `ticketCustomFields` (object, opcional): Valores de campos personalizados em formato JSON + + + + **Descrição:** Atualize um ticket de suporte existente no Zendesk. + + **Parâmetros:** + - `ticketId` (string, obrigatório): ID do ticket a ser atualizado (ex.: "35436") + - `ticketSubject` (string, opcional): Assunto atualizado do ticket + - `requesterName` (string, obrigatório): Nome do solicitante deste ticket + - `requesterEmail` (string, obrigatório): E-mail do solicitante deste ticket + - `assigneeId` (string, opcional): ID atualizado do responsável - Use as Configurações de Fluxo de Trabalho do Portal Connect + - `ticketType` (string, opcional): Tipo atualizado - Opções: problem, incident, question, task + - `ticketPriority` (string, opcional): Prioridade atualizada - Opções: urgent, high, normal, low + - `ticketStatus` (string, opcional): Status atualizado - Opções: new, open, pending, hold, solved, closed + - `ticketDueAt` (string, opcional): Nova data de vencimento (timestamp ISO 8601) + - `ticketTags` (string, opcional): Array de tags atualizadas + - `ticketExternalId` (string, opcional): Novo ID externo + - `ticketCustomFields` (object, opcional): Valores atualizados dos campos personalizados + + + + **Descrição:** Recupere um ticket específico pelo ID. + + **Parâmetros:** + - `ticketId` (string, obrigatório): ID do ticket a ser recuperado (ex.: "35436") + + + + **Descrição:** Adicione um comentário ou nota interna a um ticket existente. + + **Parâmetros:** + - `ticketId` (string, obrigatório): ID do ticket para adicionar o comentário (ex.: "35436") + - `commentBody` (string, obrigatório): Mensagem do comentário (aceita texto simples ou HTML, ex.: "Obrigado pela sua ajuda!") + - `isInternalNote` (boolean, opcional): Defina como verdadeiro para notas internas ao invés de respostas públicas (padrão é falso) + - `isPublic` (boolean, opcional): Verdadeiro para comentários públicos, falso para notas internas + + + + **Descrição:** Busque tickets usando diversos filtros e critérios. + + **Parâmetros:** + - `ticketSubject` (string, opcional): Filtrar pelo texto no assunto do ticket + - `ticketDescription` (string, opcional): Filtrar por texto na descrição e comentários do ticket + - `ticketStatus` (string, opcional): Filtrar por status - Opções: new, open, pending, hold, solved, closed + - `ticketType` (string, opcional): Filtrar por tipo - Opções: problem, incident, question, task, no_type + - `ticketPriority` (string, opcional): Filtrar por prioridade - Opções: urgent, high, normal, low, no_priority + - `requesterId` (string, opcional): Filtrar por ID do solicitante + - `assigneeId` (string, opcional): Filtrar pelo ID do agente responsável + - `recipientEmail` (string, opcional): Filtrar pelo e-mail do destinatário original + - `ticketTags` (string, opcional): Filtrar por tags do ticket + - `ticketExternalId` (string, opcional): Filtrar por ID externo + - `createdDate` (object, opcional): Filtrar por data de criação com operador (EQUALS, LESS_THAN_EQUALS, GREATER_THAN_EQUALS) e valor + - `updatedDate` (object, opcional): Filtrar por data de atualização com operador e valor + - `dueDate` (object, opcional): Filtrar por data de vencimento com operador e valor + - `sort_by` (string, opcional): Campo de ordenação - Opções: created_at, updated_at, priority, status, ticket_type + - `sort_order` (string, opcional): Direção da ordenação - Opções: asc, desc + + + +### **Gerenciamento de Usuários** + + + + **Descrição:** Crie um novo usuário no Zendesk. + + **Parâmetros:** + - `name` (string, obrigatório): Nome completo do usuário + - `email` (string, opcional): E-mail do usuário (ex.: "jane@example.com") + - `phone` (string, opcional): Telefone do usuário + - `role` (string, opcional): Papel do usuário - Opções: admin, agent, end-user + - `externalId` (string, opcional): Identificador único de outro sistema + - `details` (string, opcional): Detalhes adicionais do usuário + - `notes` (string, opcional): Notas internas sobre o usuário + + + + **Descrição:** Atualize informações de um usuário existente. + + **Parâmetros:** + - `userId` (string, obrigatório): ID do usuário a ser atualizado + - `name` (string, opcional): Nome atualizado do usuário + - `email` (string, opcional): Novo e-mail (adicionado como e-mail secundário na atualização) + - `phone` (string, opcional): Novo telefone + - `role` (string, opcional): Novo papel - Opções: admin, agent, end-user + - `externalId` (string, opcional): Novo ID externo + - `details` (string, opcional): Novos detalhes do usuário + - `notes` (string, opcional): Novas notas internas + + + + **Descrição:** Recupere um usuário específico pelo ID. + + **Parâmetros:** + - `userId` (string, obrigatório): ID do usuário a ser recuperado + + + + **Descrição:** Busque usuários utilizando vários critérios. + + **Parâmetros:** + - `name` (string, opcional): Filtrar por nome do usuário + - `email` (string, opcional): Filtrar por e-mail do usuário (ex.: "jane@example.com") + - `role` (string, opcional): Filtrar por papel - Opções: admin, agent, end-user + - `externalId` (string, opcional): Filtrar por ID externo + - `sort_by` (string, opcional): Campo de ordenação - Opções: created_at, updated_at + - `sort_order` (string, opcional): Direção de ordenação - Opções: asc, desc + + + +### **Ferramentas Administrativas** + + + + **Descrição:** Recupere todos os campos padrão e personalizados disponíveis para tickets. + + **Parâmetros:** + - `paginationParameters` (object, opcional): Configurações de paginação + - `pageCursor` (string, opcional): Cursor de página para paginação + + + + **Descrição:** Obtenha registros de auditoria (histórico somente leitura) dos tickets. + + **Parâmetros:** + - `ticketId` (string, opcional): Obtenha auditorias para um ticket específico (se vazio, recupera auditorias de todos os tickets não arquivados, ex.: "1234") + - `paginationParameters` (object, opcional): Configurações de paginação + - `pageCursor` (string, opcional): Cursor de página para paginação + + + +## Campos Personalizados + +Campos personalizados permitem armazenar informações adicionais específicas para sua organização: + +```json +[ + { "id": 27642, "value": "745" }, + { "id": 27648, "value": "yes" } +] +``` + +## Níveis de Prioridade dos Tickets + +Compreendendo os níveis de prioridade: + +- **urgent** - Questões críticas que exigem atenção imediata +- **high** - Questões importantes que devem ser tratadas rapidamente +- **normal** - Prioridade padrão para a maioria dos tickets +- **low** - Questões menores que podem ser tratadas quando conveniente + +## Fluxo de Status dos Tickets + +Progresso padrão de status dos tickets: + +- **new** - Recém-criado, ainda não atribuído +- **open** - Em andamento +- **pending** - Aguardando resposta do cliente ou ação externa +- **hold** - Pausa temporária +- **solved** - Problema resolvido, aguardando confirmação do cliente +- **closed** - Ticket finalizado e fechado + +## Exemplos de Uso + +### Configuração Básica de Agente Zendesk + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +# Obtenha as ferramentas enterprise (as ferramentas Zendesk serão incluídas) +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +# Crie um agente com capacidades Zendesk +zendesk_agent = Agent( + role="Gerente de Suporte", + goal="Gerenciar tickets de suporte ao cliente e oferecer excelente atendimento", + backstory="Um assistente de IA especializado em operações de suporte ao cliente e gerenciamento de tickets.", + tools=[enterprise_tools] +) + +# Tarefa para criar um novo ticket de suporte +create_ticket_task = Task( + description="Crie um ticket de suporte de alta prioridade para John Smith que não consegue acessar sua conta após redefinir a senha", + agent=zendesk_agent, + expected_output="Ticket de suporte criado com sucesso com o ID do ticket" +) + +# Execute a tarefa +crew = Crew( + agents=[zendesk_agent], + tasks=[create_ticket_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Zendesk Específicas + +```python +from crewai_tools import CrewaiEnterpriseTools + +# Obtenha apenas ferramentas Zendesk específicas +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token", + actions_list=["zendesk_create_ticket", "zendesk_update_ticket", "zendesk_add_comment_to_ticket"] +) + +support_agent = Agent( + role="Agente de Suporte ao Cliente", + goal="Atender consultas de clientes e resolver issues de suporte de forma eficiente", + backstory="Um agente de suporte experiente que se especializa em resolução de tickets e comunicação com clientes.", + tools=enterprise_tools +) + +# Tarefa para gerenciar o fluxo de suporte +support_task = Task( + description="Crie um ticket para problemas de login, adicione comentários de troubleshooting e atualize o status para resolvido", + agent=support_agent, + expected_output="Ticket de suporte gerenciado através de todo o fluxo de resolução" +) + +crew = Crew( + agents=[support_agent], + tasks=[support_task] +) + +crew.kickoff() +``` + +### Gerenciamento Avançado de Tickets + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +ticket_manager = Agent( + role="Gerente de Tickets", + goal="Gerenciar fluxos de tickets de suporte e garantir resolução tempestiva", + backstory="Um assistente de IA que se especializa em triagem de tickets de suporte e otimização de fluxos de trabalho.", + tools=[enterprise_tools] +) + +# Tarefa para gerenciar o ciclo de vida do ticket +ticket_workflow = Task( + description=""" + 1. Crie um novo ticket de suporte para problemas de acesso à conta + 2. Adicione notas internas com as etapas de troubleshooting + 3. Atualize a prioridade do ticket de acordo com o nível do cliente + 4. Adicione comentários de resolução e feche o ticket + """, + agent=ticket_manager, + expected_output="Ciclo de vida completo do ticket gerenciado da criação à resolução" +) + +crew = Crew( + agents=[ticket_manager], + tasks=[ticket_workflow] +) + +crew.kickoff() +``` + +### Análise e Relatórios de Suporte + +```python +from crewai import Agent, Task, Crew +from crewai_tools import CrewaiEnterpriseTools + +enterprise_tools = CrewaiEnterpriseTools( + enterprise_token="your_enterprise_token" +) + +support_analyst = Agent( + role="Analista de Suporte", + goal="Analisar métricas de suporte e gerar insights para desempenho da equipe", + backstory="Um IA analítico que se destaca na extração de insights a partir de dados de suporte e padrões de tickets.", + tools=[enterprise_tools] +) + +# Tarefa complexa envolvendo análise e geração de relatórios +analytics_task = Task( + description=""" + 1. Busque todos os tickets abertos nos últimos 30 dias + 2. Analise tempos de resolução dos tickets e satisfação do cliente + 3. Identifique problemas comuns e padrões de suporte + 4. Gere relatório semanal de desempenho do suporte + """, + agent=support_analyst, + expected_output="Relatório analítico abrangente de suporte com insights de desempenho e recomendações" +) + +crew = Crew( + agents=[support_analyst], + tasks=[analytics_task] +) + +crew.kickoff() +``` \ No newline at end of file diff --git a/docs/pt-BR/enterprise/introduction.mdx b/docs/pt-BR/enterprise/introduction.mdx new file mode 100644 index 000000000..f0e2c2e62 --- /dev/null +++ b/docs/pt-BR/enterprise/introduction.mdx @@ -0,0 +1,99 @@ +--- +title: "CrewAI Enterprise" +description: "Implemente, monitore e escale seus fluxos de trabalho de agentes de IA" +icon: "globe" +--- + +## Introdução + +CrewAI Enterprise fornece uma plataforma para implementar, monitorar e escalar seus crews e agentes em um ambiente de produção. + + + CrewAI Enterprise Dashboard + + +CrewAI Enterprise expande o poder do framework open-source com funcionalidades projetadas para implantações em produção, colaboração e escalabilidade. Implemente seus crews em uma infraestrutura gerenciada e monitore sua execução em tempo real. + +## Principais Funcionalidades + + + + Implemente seus crews em uma infraestrutura gerenciada com apenas alguns cliques + + + Acesse seus crews implantados via REST API para integração com sistemas existentes + + + Monitore seus crews com rastreamentos de execução e logs detalhados + + + Publique e instale ferramentas para aprimorar as capacidades de seus crews + + + Transmita eventos e atualizações em tempo real para seus sistemas + + + Crie e personalize crews utilizando uma interface no-code/low-code + + + +## Opções de Implantação + + + + Conecte-se diretamente aos seus repositórios do GitHub para implementar código + + + Implemente crews criados pela interface no-code do Crew Studio + + + Use o CrewAI CLI para fluxos de trabalho de implantação mais avançados + + + +## Primeiros Passos + + + + Crie sua conta em [app.crewai.com](https://app.crewai.com) + + Cadastre-se + + + + Utilize código ou o Crew Studio para construir seu crew + + Construir Crew + + + + Implemente seu crew na plataforma Enterprise + + Implantar Crew + + + + Integre-se ao seu crew através dos endpoints de API gerados + + Usar a API do Crew + + + + +Para instruções detalhadas, consulte nosso [guia de implantação](/pt-BR/enterprise/guides/deploy-crew) ou clique no botão abaixo para começar. diff --git a/docs/pt-BR/enterprise/resources/frequently-asked-questions.mdx b/docs/pt-BR/enterprise/resources/frequently-asked-questions.mdx new file mode 100644 index 000000000..756466dbf --- /dev/null +++ b/docs/pt-BR/enterprise/resources/frequently-asked-questions.mdx @@ -0,0 +1,151 @@ +--- +title: FAQs +description: "Perguntas frequentes sobre CrewAI Enterprise" +icon: "circle-question" +--- + + + + No processo hierárquico, um agente gerente é criado automaticamente e coordena o fluxo de trabalho, delegando tarefas e validando resultados para uma execução eficiente e simplificada. O agente gerente utiliza ferramentas para facilitar a delegação e execução de tarefas por agentes sob sua orientação. O LLM do gerente é fundamental para o processo hierárquico e deve ser configurado corretamente para funcionar adequadamente. + + + + A documentação mais atualizada da CrewAI está disponível em nosso site oficial de documentação: https://docs.crewai.com/ + CrewAI Docs + + + + #### Processo Hierárquico: + - As tarefas são delegadas e executadas com base em uma cadeia de comando estruturada + - Um modelo de linguagem do gerente (`manager_llm`) deve ser especificado para o agente gerente + - O agente gerente supervisiona a execução de tarefas, planejamento, delegação e validação + - As tarefas não são pré-atribuídas; o gerente aloca tarefas para os agentes com base em suas capacidades + + #### Processo Sequencial: + - As tarefas são executadas uma após a outra, garantindo uma progressão ordenada + - O resultado de uma tarefa serve como contexto para a próxima + - A execução das tarefas segue a ordem predefinida na lista de tarefas + + #### Qual Processo é Melhor para Projetos Complexos? + O processo hierárquico é mais adequado para projetos complexos porque permite: + - **Alocação e delegação dinâmica de tarefas**: O agente gerente pode atribuir tarefas de acordo com as capacidades dos agentes + - **Validação e supervisão estruturadas**: O agente gerente revisa os resultados das tarefas e garante a conclusão + - **Gestão de tarefas complexas**: Controle preciso da disponibilidade de ferramentas por agente + + + + - **Aprendizado adaptativo**: As crews tornam-se mais eficientes ao longo do tempo, adaptando-se a novas informações e aprimorando sua abordagem às tarefas + - **Personalização aprimorada**: A memória permite que os agentes recordem preferências do usuário e interações anteriores, possibilitando experiências personalizadas + - **Resolução aprimorada de problemas**: O acesso a um repositório rico em memória auxilia os agentes a tomarem decisões mais informadas, baseando-se em aprendizados anteriores e insights contextuais + + + + Definir um limite máximo de RPM para um agente evita que ele faça solicitações excessivas a serviços externos, o que pode ajudar a evitar limites de taxa e melhorar o desempenho. + + + + A entrada humana permite que os agentes solicitem informações adicionais ou esclarecimentos quando necessário. Este recurso é fundamental em processos de tomada de decisão complexos ou quando os agentes precisam de mais detalhes para concluir uma tarefa com eficácia. + + Para integrar a entrada humana na execução do agente, defina a flag `human_input` na definição da tarefa. Quando habilitada, o agente solicitará a entrada do usuário antes de entregar sua resposta final. Essa entrada pode fornecer contexto extra, esclarecer ambiguidades ou validar a saída do agente. + + Para orientações detalhadas de implementação, veja nosso [guia Human-in-the-Loop](/pt-BR/how-to/human-in-the-loop). + + + + A CrewAI oferece diversas opções avançadas de customização: + + - **Customização de Modelo de Linguagem**: Os agentes podem ser personalizados com modelos de linguagem específicos (`llm`) e modelos de linguagem para chamadas de função (`function_calling_llm`) + - **Configurações de Desempenho e Debug**: Ajuste o desempenho do agente e monitore suas operações + - **Modo Verbose**: Habilita registros detalhados das ações do agente, útil para depuração e otimização + - **Limite de RPM**: Define o número máximo de solicitações por minuto (`max_rpm`) + - **Máximo de Iterações**: O atributo `max_iter` permite definir o número máximo de iterações que um agente pode executar para uma única tarefa + - **Delegação e Autonomia**: Controle a capacidade do agente de delegar ou fazer perguntas com o atributo `allow_delegation` (padrão: True) + - **Integração de Entrada Humana**: Os agentes podem solicitar informações adicionais ou esclarecimentos quando necessário + + + + A entrada humana é especialmente útil quando: + - **Os agentes precisam de informações adicionais ou esclarecimentos**: Quando se deparam com ambiguidade ou dados incompletos + - **Os agentes precisam tomar decisões complexas ou sensíveis**: A entrada humana pode auxiliar em decisões éticas ou de nuances + - **Supervisão e validação da saída do agente**: A entrada humana pode ajudar a validar resultados e prevenir erros + - **Personalização do comportamento do agente**: Entradas humanas podem fornecer feedback para aprimorar respostas dos agentes ao longo do tempo + - **Identificação e resolução de erros ou limitações**: A entrada humana auxilia a suprir lacunas de capacidade dos agentes + + + + Os diferentes tipos de memória disponíveis na CrewAI são: + - **Memória de curto prazo**: Armazenamento temporário para contexto imediato + - **Memória de longo prazo**: Armazenamento persistente para padrões aprendidos e informações + - **Memória de entidade**: Armazenamento focado em entidades específicas e seus atributos + - **Memória contextual**: Memória que mantém o contexto ao longo das interações + + Saiba mais sobre os diferentes tipos de memória: + CrewAI Memory + + + + Para usar Output Pydantic em uma tarefa, você precisa definir a saída esperada da tarefa como um modelo Pydantic. Veja um exemplo rápido: + + + + ```python + from pydantic import BaseModel + + class User(BaseModel): + name: str + age: int + ``` + + + + ```python + from crewai import Task, Crew, Agent + from my_models import User + + task = Task( + description="Create a user with the provided name and age", + expected_output=User, # This is the Pydantic model + agent=agent, + tools=[tool1, tool2] + ) + ``` + + + + ```python + from crewai import Agent + from my_models import User + + agent = Agent( + role='User Creator', + goal='Create users', + backstory='I am skilled in creating user accounts', + tools=[tool1, tool2], + output_pydantic=User + ) + ``` + + + + Aqui está um tutorial de como obter saídas estruturadas de forma consistente dos seus agentes: + + + + + + + Você pode criar ferramentas personalizadas herdando da classe `BaseTool` fornecida pela CrewAI ou usando o decorador de ferramenta. Herdar envolve definir uma nova classe que herda de `BaseTool`, especificando o nome, a descrição e o método `_run` para a lógica operacional. O decorador de ferramenta permite criar um objeto `Tool` diretamente com os atributos necessários e uma lógica funcional. + + CrewAI Tools Guide + + + + O atributo `max_rpm` define o número máximo de solicitações por minuto que a crew pode realizar para evitar limites de taxa, e irá sobrescrever as definições de `max_rpm` dos agentes individuais se você defini-lo. + + diff --git a/docs/pt-BR/examples/example.mdx b/docs/pt-BR/examples/example.mdx new file mode 100644 index 000000000..2105d3265 --- /dev/null +++ b/docs/pt-BR/examples/example.mdx @@ -0,0 +1,62 @@ +--- +title: Exemplos CrewAI +description: Uma coleção de exemplos que mostram como usar o framework CrewAI para automatizar fluxos de trabalho. +icon: rocket-launch +--- + + + + Automatize a criação de estratégias de marketing com CrewAI. + + + Crie um roteiro de viagem surpresa com CrewAI. + + + Relacione um perfil a vagas de emprego com CrewAI. + + + Crie uma vaga de emprego com CrewAI. + + + Crie um jogo com CrewAI. + + + Encontre candidatos a vagas com CrewAI. + + \ No newline at end of file diff --git a/docs/pt-BR/guides/advanced/customizing-prompts.mdx b/docs/pt-BR/guides/advanced/customizing-prompts.mdx new file mode 100644 index 000000000..599746ea5 --- /dev/null +++ b/docs/pt-BR/guides/advanced/customizing-prompts.mdx @@ -0,0 +1,316 @@ +--- +title: Personalizando Prompts +description: Aprofunde-se na personalização de prompts de baixo nível no CrewAI, habilitando casos de uso super customizados e complexos para diferentes modelos e idiomas. +icon: message-pen +--- + +## Por Que Personalizar Prompts? + +Embora os prompts padrão do CrewAI funcionem bem para muitos cenários, a personalização de baixo nível permite comportamentos de agentes significativamente mais flexíveis e poderosos. Veja por que você pode querer aproveitar esse controle mais profundo: + +1. **Otimizar para LLMs específicas** – Diferentes modelos (como GPT-4, Claude ou Llama) funcionam melhor com formatos de prompt adaptados às suas arquiteturas exclusivas. +2. **Alterar o idioma** – Construa agentes que operam exclusivamente em idiomas além do inglês, lidando com nuances com precisão. +3. **Especializar para domínios complexos** – Adapte prompts para setores altamente especializados como saúde, finanças ou jurídico. +4. **Ajustar tom e estilo** – Torne os agentes mais formais, casuais, criativos ou analíticos. +5. **Suportar casos de uso super customizados** – Utilize estruturas e formatações avançadas de prompt para atender requisitos detalhados e específicos do projeto. + +Este guia explora como acessar os prompts do CrewAI em um nível mais baixo, oferecendo controle granular sobre como os agentes pensam e interagem. + +## Entendendo o Sistema de Prompt do CrewAI + +Nos bastidores, o CrewAI adota um sistema de prompt modular que pode ser amplamente customizado: + +- **Templates de agente** – Determinam o modo como cada agente aborda o papel que lhe foi atribuído. +- **Prompt slices** – Controlam comportamentos especializados como tarefas, o uso de ferramentas e a estrutura de saída. +- **Tratamento de erros** – Definem como os agentes respondem a falhas, exceções ou timeouts. +- **Prompts específicos de ferramentas** – Definem instruções detalhadas para como as ferramentas são invocadas ou utilizadas. + +Confira os [templates de prompt originais no repositório do CrewAI](https://github.com/crewAIInc/crewAI/blob/main/src/crewai/translations/en.json) para ver como esses elementos são organizados. A partir daí, você pode sobrescrever ou adaptar conforme necessário para desbloquear comportamentos avançados. + +## Entendendo as Instruções de Sistema Padrão + + +**Questão de Transparência em Produção**: O CrewAI injeta automaticamente instruções padrão nos seus prompts que talvez você não conheça. Esta seção explica o que acontece nos bastidores e como obter controle total. + + +Ao definir um agente com `role`, `goal` e `backstory`, o CrewAI automaticamente adiciona instruções de sistema adicionais que controlam a formatação e o comportamento. Entender essas injeções padrão é essencial para sistemas em produção onde você precisa de total transparência nos prompts. + +### O Que CrewAI Injeta Automaticamente + +Baseado na configuração do seu agente, o CrewAI adiciona diferentes instruções padrão: + +#### Para Agentes Sem Ferramentas +```text +"I MUST use these formats, my job depends on it!" +``` + +#### Para Agentes Com Ferramentas +```text +"IMPORTANT: Use the following format in your response: + +Thought: you should always think about what to do +Action: the action to take, only one name of [tool_names] +Action Input: the input to the action, just a simple JSON object... +``` + +#### Para Saídas Estruturadas (JSON/Pydantic) +```text +"Ensure your final answer contains only the content in the following format: {output_format} +Ensure the final output does not include any code block markers like ```json or ```python." +``` + +### Visualizando o Prompt de Sistema Completo + +Para ver exatamente qual prompt está sendo enviado para seu LLM, você pode inspecionar o prompt gerado: + +```python +from crewai import Agent, Crew, Task +from crewai.utilities.prompts import Prompts + +# Crie seu agente +agent = Agent( + role="Data Analyst", + goal="Analyze data and provide insights", + backstory="You are an expert data analyst with 10 years of experience.", + verbose=True +) + +# Crie uma tarefa de exemplo +task = Task( + description="Analyze the sales data and identify trends", + expected_output="A detailed analysis with key insights and trends", + agent=agent +) + +# Crie o gerador de prompt +prompt_generator = Prompts( + agent=agent, + has_tools=len(agent.tools) > 0, + use_system_prompt=agent.use_system_prompt +) + +# Gere e inspecione o prompt atual +generated_prompt = prompt_generator.task_execution() + +# Imprima o prompt completo de sistema que será enviado ao LLM +if "system" in generated_prompt: + print("=== SYSTEM PROMPT ===") + print(generated_prompt["system"]) + print("\n=== USER PROMPT ===") + print(generated_prompt["user"]) +else: + print("=== COMPLETE PROMPT ===") + print(generated_prompt["prompt"]) + +# Você também pode ver como a descrição da tarefa é formatada +print("\n=== TASK CONTEXT ===") +print(f"Task Description: {task.description}") +print(f"Expected Output: {task.expected_output}") +``` + +### Sobrescrevendo Instruções Padrão + +Você tem várias opções para obter controle total sobre os prompts: + +#### Opção 1: Templates Personalizados (Recomendado) +```python +from crewai import Agent + +# Defina seu próprio template de sistema sem instruções padrão +custom_system_template = """You are {role}. {backstory} +Your goal is: {goal} + +Respond naturally and conversationally. Focus on providing helpful, accurate information.""" + +custom_prompt_template = """Task: {input} + +Please complete this task thoughtfully.""" + +agent = Agent( + role="Research Assistant", + goal="Help users find accurate information", + backstory="You are a helpful research assistant.", + system_template=custom_system_template, + prompt_template=custom_prompt_template, + use_system_prompt=True # Use mensagens separadas system/user +) +``` + +#### Opção 2: Arquivo de Prompt Personalizado +Crie um arquivo `custom_prompts.json` para sobrescrever slices específicas de prompt: + +```json +{ + "slices": { + "no_tools": "\nProvide your best answer in a natural, conversational way.", + "tools": "\nYou have access to these tools: {tools}\n\nUse them when helpful, but respond naturally.", + "formatted_task_instructions": "Format your response as: {output_format}" + } +} +``` + +Em seguida, utilize no seu crew: + +```python +crew = Crew( + agents=[agent], + tasks=[task], + prompt_file="custom_prompts.json", + verbose=True +) +``` + +#### Opção 3: Desativar Prompts de Sistema para Modelos o1 +```python +agent = Agent( + role="Analyst", + goal="Analyze data", + backstory="Expert analyst", + use_system_prompt=False # Desativa separação de mensagens system prompt +) +``` + +### Depuração com Ferramentas de Observabilidade + +Para garantir transparência em produção, integre com plataformas de observabilidade para monitorar todos os prompts e interações com LLM. Isso permite que você veja exatamente quais prompts (incluindo instruções padrão) estão sendo enviados para os seus LLMs. + +Veja nossa [documentação sobre Observabilidade](/pt-BR/observability/overview) para guias detalhados de integração com diversas plataformas como Langfuse, MLflow, Weights & Biases e soluções de logging customizadas. + +### Boas Práticas para Produção + +1. **Sempre inspecione prompts gerados** antes de implantar em produção +2. **Use templates customizados** quando precisar de controle total sobre o conteúdo do prompt +3. **Integre ferramentas de observabilidade** para monitoramento contínuo de prompts (veja [docs de Observabilidade](/pt-BR/observability/overview)) +4. **Teste com diferentes LLMs** já que instruções padrão podem se comportar de maneira diferente em cada modelo +5. **Documente suas customizações de prompt** para transparência da equipe + + +As instruções padrão existem para garantir comportamento consistente nos agentes, mas podem interferir com requisitos de domínio específicos. Use as opções de customização acima para manter controle total sobre o comportamento do seu agente em sistemas de produção. + + +## Melhores Práticas para Gerenciar Arquivos de Prompt + +Ao realizar personalização de prompts em baixo nível, siga estas diretrizes para manter tudo organizado e fácil de manter: + +1. **Mantenha arquivos separados** – Armazene seus prompts personalizados em arquivos JSON dedicados fora do código principal. +2. **Controle de versão** – Acompanhe as alterações no seu repositório, garantindo documentação clara das mudanças nos prompts ao longo do tempo. +3. **Organize por modelo ou idioma** – Utilize nomes como `prompts_llama.json` ou `prompts_es.json` para identificar rapidamente configurações especializadas. +4. **Documente as alterações** – Adicione comentários ou mantenha um README detalhando o propósito e o escopo das customizações. +5. **Minimize alterações** – Sobrescreva apenas os slices específicos que realmente precisam de ajuste, mantendo a funcionalidade padrão para o restante. + +## O Jeito Mais Simples de Personalizar Prompts + +Uma abordagem direta é criar um arquivo JSON para os prompts que deseja sobrescrever e então indicar este arquivo no seu Crew: + +1. Crie um arquivo JSON com os slices de prompt atualizados. +2. Referencie este arquivo no parâmetro `prompt_file` do seu Crew. + +O CrewAI então mescla suas customizações com os padrões, assim você não precisa redefinir todos os prompts. Veja como: + +### Exemplo: Customização Básica de Prompt + +Crie um arquivo `custom_prompts.json` com os prompts que deseja modificar. Certifique-se de listar todos os prompts de nível superior que ele deve conter, não apenas suas alterações: + +```json +{ + "slices": { + "format": "When responding, follow this structure:\n\nTHOUGHTS: Your step-by-step thinking\nACTION: Any tool you're using\nRESULT: Your final answer or conclusion" + } +} +``` + +Integre assim: + +```python +from crewai import Agent, Crew, Task, Process + +# Crie agentes e tarefas normalmente +researcher = Agent( + role="Research Specialist", + goal="Find information on quantum computing", + backstory="You are a quantum physics expert", + verbose=True +) + +research_task = Task( + description="Research quantum computing applications", + expected_output="A summary of practical applications", + agent=researcher +) + +# Crie um crew com seu arquivo de prompt personalizado +crew = Crew( + agents=[researcher], + tasks=[research_task], + prompt_file="path/to/custom_prompts.json", + verbose=True +) + +# Execute o crew +result = crew.kickoff() +``` + +Com essas poucas edições, você conquista controle de baixo nível sobre como seus agentes se comunicam e solucionam tarefas. + +## Otimizando para Modelos Específicos + +Modelos diferentes respondem melhor a estruturas de prompt diferentes. Ajustes mais profundos podem aumentar significativamente o desempenho ao alinhar seus prompts às nuances de cada modelo. + +### Exemplo: Template de Prompt para Llama 3.3 + +Por exemplo, ao lidar com o Llama 3.3 da Meta, a personalização de baixo nível pode refletir a estrutura recomendada descrita em: +https://www.llama.com/docs/model-cards-and-prompt-formats/llama3_1/#prompt-template + +Veja um exemplo destacando como você pode ajustar um Agent para usar o Llama 3.3 em código: + +```python +from crewai import Agent, Crew, Task, Process +from crewai_tools import DirectoryReadTool, FileReadTool + +# Defina templates para mensagens de system, user (prompt) e assistant (resposta) +system_template = """<|begin_of_text|><|start_header_id|>system<|end_header_id|>{{ .System }}<|eot_id|>""" +prompt_template = """<|start_header_id|>user<|end_header_id|>{{ .Prompt }}<|eot_id|>""" +response_template = """<|start_header_id|>assistant<|end_header_id|>{{ .Response }}<|eot_id|>""" + +# Crie um Agent usando layouts específicos do Llama +principal_engineer = Agent( + role="Principal Engineer", + goal="Oversee AI architecture and make high-level decisions", + backstory="You are the lead engineer responsible for critical AI systems", + verbose=True, + llm="groq/llama-3.3-70b-versatile", # Usando o modelo Llama 3 + system_template=system_template, + prompt_template=prompt_template, + response_template=response_template, + tools=[DirectoryReadTool(), FileReadTool()] +) + +# Defina uma tarefa de exemplo +engineering_task = Task( + description="Review AI implementation files for potential improvements", + expected_output="A summary of key findings and recommendations", + agent=principal_engineer +) + +# Crie um Crew para a tarefa +llama_crew = Crew( + agents=[principal_engineer], + tasks=[engineering_task], + process=Process.sequential, + verbose=True +) + +# Execute o crew +result = llama_crew.kickoff() +print(result.raw) +``` + +Com essa configuração, você exerce controle abrangente e de baixo nível sobre seus fluxos de trabalho baseados em Llama sem precisar de um arquivo JSON separado. + +## Conclusão + +A personalização de prompts em baixo nível no CrewAI abre portas para casos de uso super customizados e complexos. Mantendo arquivos de prompt organizados (ou templates inline diretos), é possível acomodar diferentes modelos, idiomas e domínios especializados. Esse nível de flexibilidade garante que você possa criar exatamente o comportamento de IA que precisa, sabendo que o CrewAI ainda fornece padrões confiáveis quando você não sobrescreve. + + +Agora você tem a base para customizações avançadas de prompt no CrewAI. Seja adaptando para estruturas específicas de modelo ou restrições de domínio, esta abordagem de baixo nível permite moldar as interações dos agentes de forma altamente especializada. + diff --git a/docs/pt-BR/guides/advanced/fingerprinting.mdx b/docs/pt-BR/guides/advanced/fingerprinting.mdx new file mode 100644 index 000000000..53ce8660b --- /dev/null +++ b/docs/pt-BR/guides/advanced/fingerprinting.mdx @@ -0,0 +1,133 @@ +--- +title: Impressão digital +description: Saiba como usar o sistema de impressão digital da CrewAI para identificar e rastrear componentes de forma única durante todo o seu ciclo de vida. +icon: fingerprint +--- + +## Visão geral + +As impressões digitais na CrewAI fornecem uma maneira de identificar e rastrear componentes de forma única durante todo o seu ciclo de vida. Cada `Agent`, `Crew` e `Task` recebe automaticamente uma impressão digital única quando criado, que não pode ser sobrescrita manualmente. + +Essas impressões digitais podem ser usadas para: +- Auditoria e rastreamento do uso de componentes +- Garantir a integridade da identidade dos componentes +- Anexar metadados aos componentes +- Criar uma cadeia rastreável de operações + +## Como funciona a impressão digital + +Uma impressão digital é uma instância da classe `Fingerprint` do módulo `crewai.security`. Cada impressão digital contém: + +- Uma string UUID: Um identificador único para o componente, gerado automaticamente e que não pode ser definido manualmente +- Um timestamp de criação: Quando a impressão digital foi gerada, definido automaticamente e que não pode ser modificado manualmente +- Metadados: Um dicionário de informações adicionais que pode ser customizado + +As impressões digitais são geradas e atribuídas automaticamente quando um componente é criado. Cada componente expõe sua impressão digital por meio de uma propriedade de somente leitura. + +## Uso básico + +### Acessando impressões digitais + +```python +from crewai import Agent, Crew, Task + +# Criar componentes - impressões digitais são geradas automaticamente +agent = Agent( + role="Data Scientist", + goal="Analyze data", + backstory="Expert in data analysis" +) + +crew = Crew( + agents=[agent], + tasks=[] +) + +task = Task( + description="Analyze customer data", + expected_output="Insights from data analysis", + agent=agent +) + +# Acessar as impressões digitais +agent_fingerprint = agent.fingerprint +crew_fingerprint = crew.fingerprint +task_fingerprint = task.fingerprint + +# Imprimir as strings UUID +print(f"Agent fingerprint: {agent_fingerprint.uuid_str}") +print(f"Crew fingerprint: {crew_fingerprint.uuid_str}") +print(f"Task fingerprint: {task_fingerprint.uuid_str}") +``` + +### Trabalhando com metadados das impressões digitais + +Você pode adicionar metadados às impressões digitais para fornecer contexto adicional: + +```python +# Adicionar metadados à impressão digital do agente +agent.security_config.fingerprint.metadata = { + "version": "1.0", + "department": "Data Science", + "project": "Customer Analysis" +} + +# Acessar os metadados +print(f"Agent metadata: {agent.fingerprint.metadata}") +``` + +## Persistência das impressões digitais + +As impressões digitais foram projetadas para persistir e permanecer inalteradas durante todo o ciclo de vida de um componente. Se você modificar um componente, a impressão digital permanece a mesma: + +```python +original_fingerprint = agent.fingerprint.uuid_str + +# Modificar o agente +agent.goal = "New goal for analysis" + +# A impressão digital permanece inalterada +assert agent.fingerprint.uuid_str == original_fingerprint +``` + +## Impressões digitais determinísticas + +Apesar de não ser possível definir diretamente o UUID e o timestamp de criação, é possível criar impressões digitais determinísticas usando o método `generate` com uma seed: + +```python +from crewai.security import Fingerprint + +# Criar uma impressão digital determinística usando uma string seed +deterministic_fingerprint = Fingerprint.generate(seed="my-agent-id") + +# A mesma seed sempre gera a mesma impressão digital +same_fingerprint = Fingerprint.generate(seed="my-agent-id") +assert deterministic_fingerprint.uuid_str == same_fingerprint.uuid_str + +# Também é possível definir metadados +custom_fingerprint = Fingerprint.generate( + seed="my-agent-id", + metadata={"version": "1.0"} +) +``` + +## Uso avançado + +### Estrutura da impressão digital + +Cada impressão digital possui a seguinte estrutura: + +```python +from crewai.security import Fingerprint + +fingerprint = agent.fingerprint + +# String UUID - identificador único (gerado automaticamente) +uuid_str = fingerprint.uuid_str # e.g., "123e4567-e89b-12d3-a456-426614174000" + +# Timestamp de criação (gerado automaticamente) +created_at = fingerprint.created_at # Um objeto datetime + +# Metadados - informações adicionais (podem ser customizadas) +metadata = fingerprint.metadata # Um dicionário, padrão {} +``` \ No newline at end of file diff --git a/docs/pt-BR/guides/agents/crafting-effective-agents.mdx b/docs/pt-BR/guides/agents/crafting-effective-agents.mdx new file mode 100644 index 000000000..9941fe032 --- /dev/null +++ b/docs/pt-BR/guides/agents/crafting-effective-agents.mdx @@ -0,0 +1,452 @@ +--- +title: Criando Agentes Eficazes +description: Aprenda as melhores práticas para projetar agentes de IA poderosos e especializados que colaboram de forma eficaz para resolver problemas complexos. +icon: robot +--- + +## A Arte e a Ciência do Design de Agentes + +No núcleo do CrewAI está o agente – uma entidade de IA especializada projetada para desempenhar funções específicas dentro de um framework colaborativo. Embora criar agentes básicos seja simples, criar agentes verdadeiramente eficazes que geram resultados excepcionais requer a compreensão de princípios fundamentais de design e boas práticas. + +Este guia vai ajudá-lo a dominar a arte de projetar agentes, permitindo criar personas de IA especializadas que colaboram de forma eficaz, pensam criticamente e produzem resultados de alta qualidade adaptados às suas necessidades específicas. + +### Por Que o Design de Agentes é Importante + +A forma como você define seus agentes impacta significativamente: + +1. **Qualidade do resultado**: Agentes bem projetados produzem resultados mais relevantes e de alta qualidade +2. **Eficiência da colaboração**: Agentes com habilidades complementares trabalham juntos de maneira mais eficiente +3. **Desempenho nas tarefas**: Agentes com papéis e objetivos claros executam tarefas de forma mais eficaz +4. **Escalabilidade do sistema**: Agentes bem projetados podem ser reutilizados em múltiplos crews e contextos + +Vamos explorar as melhores práticas para criar agentes que se destacam nessas dimensões. + +## A Regra 80/20: Foque Mais nas Tarefas do que nos Agentes + +Ao construir sistemas de IA eficazes, lembre-se deste princípio crucial: **80% do seu esforço deve ser dedicado ao design das tarefas, e apenas 20% à definição dos agentes**. + +Por quê? Porque mesmo o agente mais perfeitamente definido irá falhar com tarefas mal elaboradas, mas tarefas bem projetadas podem elevar até mesmo agentes simples. Isso significa: + +- Dedique a maior parte do seu tempo escrevendo instruções claras para as tarefas +- Defina entradas detalhadas e saídas esperadas +- Adicione exemplos e contexto para orientar a execução +- Reserve o tempo restante para o papel, objetivo e histórico do agente + +Isso não quer dizer que o design do agente não seja importante – ele é, sim. Mas o design das tarefas é onde ocorrem a maioria das falhas de execução, então priorize de acordo. + +## Princípios Fundamentais do Design de Agentes Eficazes + +### 1. O Framework Papel–Objetivo–Histórico + +Os agentes mais poderosos no CrewAI têm uma base sólida em três elementos-chave: + +#### Papel: A Função Especializada do Agente + +O papel define o que o agente faz e sua área de especialização. Ao criar papéis: + +- **Seja específico e especializado**: Em vez de “Escritor”, use “Especialista em Documentação Técnica” ou “Contador de Histórias Criativo” +- **Alinhe com profissões do mundo real**: Baseie os papéis em arquétipos profissionais reconhecíveis +- **Inclua expertise no domínio**: Especifique o campo de conhecimento do agente (ex: “Analista Financeiro especializado em tendências de mercado”) + +**Exemplos de papéis eficazes:** +```yaml +role: "Pesquisador Sênior de UX especializado em análise de entrevistas com usuários" +role: "Arquiteto de Software Full-Stack com expertise em sistemas distribuídos" +role: "Diretor de Comunicação Corporativa especializado em gestão de crises" +``` + +#### Objetivo: A Finalidade e Motivação do Agente + +O objetivo direciona os esforços do agente e orienta seu processo de tomada de decisão. Objetivos eficazes devem: + +- **Ser claros e focados em resultado**: Defina o que o agente precisa alcançar +- **Enfatizar padrões de qualidade**: Inclua expectativas sobre a qualidade do trabalho +- **Incorporar critérios de sucesso**: Ajude o agente a entender o que é considerado “bom” + +**Exemplos de objetivos eficazes:** +```yaml +goal: "Descobrir insights acionáveis analisando dados de entrevistas, identificando padrões recorrentes, necessidades não atendidas e oportunidades de melhoria" +goal: "Projetar arquiteturas de sistemas robustas e escaláveis que equilibrem performance, manutenção e custo-benefício" +goal: "Criar comunicações de crise claras e empáticas, abordando as preocupações das partes interessadas e protegendo a reputação organizacional" +``` + +#### Histórico: Experiência e Perspectiva do Agente + +O histórico aprofunda o agente, influenciando como ele aborda problemas e interage com os demais. Bons históricos: + +- **Estabelecem expertise e experiência**: Explique como o agente adquiriu suas habilidades +- **Definem estilo de trabalho e valores**: Descreva como o agente encara seu trabalho +- **Criam uma persona coesa**: Garanta que todos os elementos do histórico estejam alinhados ao papel e ao objetivo + +**Exemplos de históricos eficazes:** +```yaml +backstory: "Você passou 15 anos conduzindo e analisando pesquisas com usuários em grandes empresas de tecnologia. Tem talento para ler nas entrelinhas e identificar padrões que outros não enxergam. Acredita que uma boa experiência do usuário é invisível e que os melhores insights vêm tanto do que os usuários não dizem quanto do que dizem." + +backstory: "Com mais de 20 anos de experiência construindo sistemas distribuídos em larga escala, você desenvolveu uma abordagem pragmática para arquitetura de software. Viu sistemas bem sucedidos e fracassados e aprendeu lições valiosas com ambos. Equilibra as melhores práticas teóricas com restrições práticas e sempre considera os aspectos de manutenção e operação em seus projetos." + +backstory: "Como um profissional de comunicação experiente que já orientou múltiplas organizações em crises de grande repercussão, você entende a importância da transparência, agilidade e empatia em respostas a crises. Tem uma abordagem metódica para criar mensagens que abordam preocupações mantendo a credibilidade da organização." +``` + +### 2. Especialistas em vez de Generalistas + +Agentes desempenham muito melhor quando recebem papéis especializados em vez de papéis genéricos. Um agente altamente focado gera resultados mais precisos e relevantes: + +**Genérico (Menos Eficaz):** +```yaml +role: "Writer" +``` + +**Especializado (Mais Eficaz):** +```yaml +role: "Redator Técnico de Blog especializado em explicar conceitos complexos de IA para públicos não técnicos" +``` + +**Vantagens dos Especialistas:** +- Compreensão mais clara do resultado esperado +- Performance mais consistente +- Melhor alinhamento com tarefas específicas +- Maior capacidade de fazer julgamentos específicos do domínio + +### 3. Equilibrando Especialização e Versatilidade + +Agentes eficazes equilibram bem a especialização (fazer uma coisa muito bem) e a versatilidade (adaptar-se a diversas situações): + +- **Especialize no papel, seja versátil na aplicação**: Crie agentes com habilidades especializadas aplicáveis em múltiplos contextos +- **Evite definições excessivamente restritas**: Garanta que agentes possam lidar com variações dentro de sua área de expertise +- **Considere o contexto colaborativo**: Projete agentes cujas especialidades complementem os demais do crew + +### 4. Definição Nível Apropriado de Expertise + +O nível de expertise atribuído ao agente determina como ele realiza as tarefas: + +- **Agentes iniciantes**: Bons para tarefas simples, brainstorm, rascunhos iniciais +- **Agentes intermediários**: Adequados para a maioria das tarefas padrão com execução confiável +- **Agentes especialistas**: Ideais para tarefas complexas e especializadas que exigem profundidade e nuances +- **Agentes de classe mundial**: Reservados para tarefas críticas onde a qualidade excepcional é essencial + +Escolha o nível de expertise baseado na complexidade da tarefa e no padrão de qualidade exigido. Em crews colaborativos, tendem a funcionar melhor equipes com níveis variados de expertise, reservando maior especialização para as funções mais chave. + +## Exemplos Práticos: Antes e Depois + +Veja exemplos de definições de agentes antes e depois de aplicar essas boas práticas: + +### Exemplo 1: Agente de Criação de Conteúdo + +**Antes:** +```yaml +role: "Writer" +goal: "Write good content" +backstory: "You are a writer who creates content for websites." +``` + +**Depois:** +```yaml +role: "Estrategista de Conteúdo B2B para Tecnologia" +goal: "Criar conteúdos envolventes e tecnicamente precisos, explicando tópicos complexos em linguagem acessível, promovendo engajamento e apoiando os objetivos do negócio" +backstory: "Você passou uma década criando conteúdos para empresas líderes em tecnologia, especializando-se na tradução de conceitos técnicos para públicos empresariais. É ótimo em pesquisa, entrevistas com especialistas e estruturação da informação para máxima clareza e impacto. Acredita que o melhor conteúdo B2B educa antes de vender, construindo confiança através da expertise genuína e não do hype de marketing." +``` + +### Exemplo 2: Agente de Pesquisa + +**Antes:** +```yaml +role: "Researcher" +goal: "Find information" +backstory: "You are good at finding information online." +``` + +**Depois:** +```yaml +role: "Especialista em Pesquisa Acadêmica de Tecnologias Emergentes" +goal: "Descobrir e sintetizar pesquisas de ponta, identificando tendências, metodologias e resultados principais, avaliando a qualidade e confiabilidade das fontes" +backstory: "Com formação em ciência da computação e biblioteconomia, você dominou a arte da pesquisa digital. Já trabalhou com equipes de pesquisa em universidades de prestígio e sabe como navegar bancos de dados acadêmicos, avaliar a qualidade das pesquisas e sintetizar descobertas em diferentes áreas. Seu método é rigoroso: sempre cruza informações e rastreia a origem dos dados antes de chegar a conclusões." +``` + +## Criando Tarefas Eficazes para seus Agentes + +Embora o design dos agentes seja importante, o design das tarefas é crítico para uma boa execução. Aqui estão as melhores práticas para definir tarefas que irão impulsionar o sucesso dos seus agentes: + +### A Anatomia de uma Tarefa Eficaz + +Uma tarefa bem projetada tem dois componentes-chave com propósitos distintos: + +#### Descrição da Tarefa: O Processo +A descrição deve focar no que fazer e como fazer, incluindo: +- Instruções detalhadas de execução +- Contexto e informações de fundo +- Escopo e restrições +- Passos do processo a serem seguidos + +#### Saída Esperada: O Entregável +A saída esperada deve definir como o resultado final deve ser apresentado: +- Especificações de formato (markdown, JSON, etc.) +- Estrutura exigida +- Critérios de qualidade +- Exemplos de bons entregáveis (sempre que possível) + +### Melhores Práticas para Design de Tarefas + +#### 1. Propósito Único, Saída Única +Tarefas funcionam melhor quando são focadas em um objetivo claro: + +**Exemplo Ruim (Muito Abrangente):** +```yaml +task_description: "Research market trends, analyze the data, and create a visualization." +``` + +**Exemplo Bom (Focado):** +```yaml +# Task 1 +research_task: + description: "Research the top 5 market trends in the AI industry for 2024." + expected_output: "A markdown list of the 5 trends with supporting evidence." + +# Task 2 +analysis_task: + description: "Analyze the identified trends to determine potential business impacts." + expected_output: "A structured analysis with impact ratings (High/Medium/Low)." + +# Task 3 +visualization_task: + description: "Create a visual representation of the analyzed trends." + expected_output: "A description of a chart showing trends and their impact ratings." +``` + +#### 2. Seja Explícito Sobre Entradas e Saídas +Sempre especifique claramente quais são as entradas da tarefa e como deve ser o resultado: + +**Exemplo:** +```yaml +analysis_task: + description: > + Analyze the customer feedback data from the CSV file. + Focus on identifying recurring themes related to product usability. + Consider sentiment and frequency when determining importance. + expected_output: > + A markdown report with the following sections: + 1. Executive summary (3-5 bullet points) + 2. Top 3 usability issues with supporting data + 3. Recommendations for improvement +``` + +#### 3. Inclua Propósito e Contexto +Explique por que a tarefa importa e como ela se encaixa no fluxo de trabalho maior: + +**Exemplo:** +```yaml +competitor_analysis_task: + description: > + Analyze our three main competitors' pricing strategies. + This analysis will inform our upcoming pricing model revision. + Focus on identifying patterns in how they price premium features + and how they structure their tiered offerings. +``` + +#### 4. Use Ferramentas de Saída Estruturada +Para saídas legíveis por máquina, especifique claramente o formato: + +**Exemplo:** +```yaml +data_extraction_task: + description: "Extract key metrics from the quarterly report." + expected_output: "JSON object with the following keys: revenue, growth_rate, customer_acquisition_cost, and retention_rate." +``` + +## Erros Comuns a Evitar + +Baseando-se em experiências de casos reais, estes são os erros mais comuns no design de agentes e tarefas: + +### 1. Instruções de Tarefa Pouco Claras + +**Problema:** Tarefas sem detalhes suficientes, dificultando a execução pelo agente. + +**Exemplo de Design Ruim:** +```yaml +research_task: + description: "Research AI trends." + expected_output: "A report on AI trends." +``` + +**Versão Melhorada:** +```yaml +research_task: + description: > + Research the top emerging AI trends for 2024 with a focus on: + 1. Enterprise adoption patterns + 2. Technical breakthroughs in the past 6 months + 3. Regulatory developments affecting implementation + + For each trend, identify key companies, technologies, and potential business impacts. + expected_output: > + A comprehensive markdown report with: + - Executive summary (5 bullet points) + - 5-7 major trends with supporting evidence + - For each trend: definition, examples, and business implications + - References to authoritative sources +``` + +### 2. "Tarefas-Deus" Que Tentam Fazer Demais + +**Problema:** Tarefas que combinam múltiplas operações complexas em um único conjunto de instruções. + +**Exemplo de Design Ruim:** +```yaml +comprehensive_task: + description: "Research market trends, analyze competitor strategies, create a marketing plan, and design a launch timeline." +``` + +**Versão Melhorada:** +Divida em tarefas sequenciais e focadas: +```yaml +# Task 1: Research +market_research_task: + description: "Research current market trends in the SaaS project management space." + expected_output: "A markdown summary of key market trends." + +# Task 2: Competitive Analysis +competitor_analysis_task: + description: "Analyze strategies of the top 3 competitors based on the market research." + expected_output: "A comparison table of competitor strategies." + context: [market_research_task] + +# Continue with additional focused tasks... +``` + +### 3. Descrição e Saída Esperada Desalinhadas + +**Problema:** O que a descrição pede não corresponde ao que a saída esperada especifica. + +**Exemplo de Design Ruim:** +```yaml +analysis_task: + description: "Analyze customer feedback to find areas of improvement." + expected_output: "A marketing plan for the next quarter." +``` + +**Versão Melhorada:** +```yaml +analysis_task: + description: "Analyze customer feedback to identify the top 3 areas for product improvement." + expected_output: "A report listing the 3 priority improvement areas with supporting customer quotes and data points." +``` + +### 4. Não Entender o Processo Você Mesmo + +**Problema:** Pedir para o agente executar tarefas que você mesmo não entende completamente. + +**Solução:** +1. Tente realizar a tarefa manualmente primeiro +2. Documente o processo, pontos de decisão e fontes de informação +3. Use esta documentação como base para a descrição da tarefa + +### 5. Uso Prematuro de Estruturas Hierárquicas + +**Problema:** Criar hierarquias de agentes desnecessariamente complexas quando processos sequenciais seriam suficientes. + +**Solução:** Comece com processos sequenciais e só adote modelos hierárquicos quando a complexidade do fluxo de trabalho realmente justificar. + +### 6. Definições Genéricas ou Pouco Claras de Agentes + +**Problema:** Definições genéricas de agentes levam a resultados genéricos. + +**Exemplo de Design Ruim:** +```yaml +agent: + role: "Business Analyst" + goal: "Analyze business data" + backstory: "You are good at business analysis." +``` + +**Versão Melhorada:** +```yaml +agent: + role: "Especialista em Métricas SaaS focado em startups em fase de crescimento" + goal: "Identificar insights acionáveis em dados de negócios que possam impactar diretamente a retenção de clientes e o crescimento de receita" + backstory: "Com mais de 10 anos analisando modelos de negócios SaaS, você desenvolveu um olhar apurado para as métricas que realmente impulsionam crescimento sustentável. Já ajudou diversas empresas a identificar pontos de alavancagem que mudaram o rumo dos negócios. Acredita em conectar dados a recomendações específicas e acionáveis, e não apenas a observações genéricas." +``` + +## Estratégias Avançadas de Design de Agentes + +### Projetando para Colaboração + +Ao criar agentes que trabalharão em conjunto em um crew, pense em: + +- **Habilidades complementares**: Projete agentes com competências distintas, porém complementares +- **Pontos de transferência**: Defina interfaces claras para a passagem de trabalho entre agentes +- **Tensão construtiva**: Às vezes, agentes com perspectivas um pouco diferentes promovem melhores resultados por meio de diálogos construtivos + +Por exemplo, um crew de criação de conteúdo pode incluir: + +```yaml +# Research Agent +role: "Research Specialist for technical topics" +goal: "Gather comprehensive, accurate information from authoritative sources" +backstory: "You are a meticulous researcher with a background in library science..." + +# Writer Agent +role: "Technical Content Writer" +goal: "Transform research into engaging, clear content that educates and informs" +backstory: "You are an experienced writer who excels at explaining complex concepts..." + +# Editor Agent +role: "Content Quality Editor" +goal: "Ensure content is accurate, well-structured, and polished while maintaining consistency" +backstory: "With years of experience in publishing, you have a keen eye for detail..." +``` + +### Criando Usuários Especializados de Ferramentas + +Alguns agentes podem ser projetados para explorar certas ferramentas de maneira eficiente: + +```yaml +role: "Data Analysis Specialist" +goal: "Derive meaningful insights from complex datasets through statistical analysis" +backstory: "With a background in data science, you excel at working with structured and unstructured data..." +tools: [PythonREPLTool, DataVisualizationTool, CSVAnalysisTool] +``` + +### Personalizando Agentes para Capacidades do LLM + +Diferentes LLMs têm pontos fortes distintos. Projete seus agentes levando essas capacidades em conta: + +```yaml +# For complex reasoning tasks +analyst: + role: "Data Insights Analyst" + goal: "..." + backstory: "..." + llm: openai/gpt-4o + +# For creative content +writer: + role: "Creative Content Writer" + goal: "..." + backstory: "..." + llm: anthropic/claude-3-opus +``` + +## Testando e Iterando no Design de Agentes + +A construção de agentes geralmente é um processo iterativo. Veja como colocar em prática: + +1. **Comece com um protótipo**: Crie uma definição inicial do agente +2. **Teste com tarefas de exemplo**: Avalie o desempenho em tarefas representativas +3. **Analise os resultados**: Identifique pontos fortes e fracos +4. **Refine a definição**: Ajuste papel, objetivo e histórico conforme suas observações +5. **Teste em colaboração**: Avalie como o agente se sai em conjunto no crew + +## Conclusão + +Criar agentes eficazes é tanto arte quanto ciência. Ao definir cuidadosamente papéis, objetivos e históricos alinhados às suas necessidades, e combinar isso com tarefas bem projetadas, você constrói colaboradores de IA especializados capazes de gerar resultados excepcionais. + +Lembre-se de que o design de agentes e tarefas é um processo iterativo. Comece com essas boas práticas, observe os agentes em ação e refine sua abordagem conforme necessário. E sempre tenha em mente a regra 80/20 – concentre a maior parte do esforço em criar tarefas claras e focadas para tirar o melhor de seus agentes. + + +Parabéns! Agora você entende os princípios e práticas do design eficaz de agentes. Aplique estas técnicas para criar agentes poderosos e especializados que trabalham juntos perfeitamente e realizam tarefas complexas. + + +## Próximos Passos + +- Experimente diferentes configurações de agentes para o seu caso de uso +- Aprenda sobre [como construir seu primeiro crew](/pt-BR/guides/crews/first-crew) para ver como agentes trabalham juntos +- Explore os [CrewAI Flows](/pt-BR/guides/flows/first-flow) para uma orquestração mais avançada diff --git a/docs/pt-BR/guides/concepts/evaluating-use-cases.mdx b/docs/pt-BR/guides/concepts/evaluating-use-cases.mdx new file mode 100644 index 000000000..4b4b8b15b --- /dev/null +++ b/docs/pt-BR/guides/concepts/evaluating-use-cases.mdx @@ -0,0 +1,503 @@ +--- +title: Avaliando Casos de Uso para CrewAI +description: Aprenda a avaliar as necessidades da sua aplicação de IA e escolher a abordagem certa entre Crews e Flows com base nos requisitos de complexidade e precisão. +icon: scale-balanced +--- + +## Entendendo o Framework de Decisão + +Ao construir aplicações de IA com CrewAI, uma das decisões mais importantes que você tomará é escolher a abordagem correta para o seu caso de uso específico. Você deve usar uma Crew? Um Flow? Uma combinação dos dois? Este guia vai ajudar você a avaliar seus requisitos e tomar decisões arquitetônicas embasadas. + +No centro dessa decisão está o entendimento da relação entre **complexidade** e **precisão** em sua aplicação: + + + Matriz de Complexidade vs. Precisão + + +Essa matriz ajuda a visualizar como diferentes abordagens se alinham com os requisitos variados de complexidade e precisão. Vamos explorar o significado de cada quadrante e como isso orienta suas escolhas arquiteturais. + +## Explicando a Matriz Complexidade-Precisão + +### O que é Complexidade? + +No contexto das aplicações CrewAI, **complexidade** refere-se a: + +- O número de etapas ou operações distintas necessárias +- A diversidade de tarefas que precisam ser realizadas +- As interdependências entre diferentes componentes +- A necessidade de lógica condicional e ramificações +- A sofisticação do fluxo de trabalho como um todo + +### O que é Precisão? + +**Precisão** nesse contexto refere-se a: + +- O grau de exatidão exigido no resultado final +- A necessidade de resultados estruturados e previsíveis +- A importância da reprodutibilidade +- O nível de controle necessário sobre cada etapa +- A tolerância à variação nos resultados + +### Os Quatro Quadrantes + +#### 1. Baixa Complexidade, Baixa Precisão + +**Características:** +- Tarefas simples e diretas +- Tolerância a alguma variação nos resultados +- Número limitado de etapas +- Aplicações criativas ou exploratórias + +**Abordagem Recomendada:** Crews simples com poucos agentes + +**Exemplos de Casos de Uso:** +- Geração básica de conteúdo +- Brainstorming de ideias +- Tarefas simples de sumarização +- Assistência à escrita criativa + +#### 2. Baixa Complexidade, Alta Precisão + +**Características:** +- Fluxos de trabalho simples que exigem resultados exatos e estruturados +- Necessidade de resultados reproduzíveis +- Poucas etapas, mas alto requisito de precisão +- Frequentemente envolve processamento ou transformação de dados + +**Abordagem Recomendada:** Flows com chamadas diretas a LLM ou Crews simples com saídas estruturadas + +**Exemplos de Casos de Uso:** +- Extração e transformação de dados +- Preenchimento e validação de formulários +- Geração estruturada de conteúdo (JSON, XML) +- Tarefas simples de classificação + +#### 3. Alta Complexidade, Baixa Precisão + +**Características:** +- Processos multiestágio com muitas etapas +- Saídas criativas ou exploratórias +- Interações complexas entre componentes +- Tolerância à variação nos resultados finais + +**Abordagem Recomendada:** Crews complexas com múltiplos agentes especializados + +**Exemplos de Casos de Uso:** +- Pesquisa e análise +- Pipelines de criação de conteúdo +- Análise exploratória de dados +- Solução criativa de problemas + +#### 4. Alta Complexidade, Alta Precisão + +**Características:** +- Fluxos de trabalho complexos que requerem saídas estruturadas +- Múltiplas etapas interdependentes com rígida exigência de precisão +- Necessidade tanto de processamento sofisticado quanto de resultados precisos +- Frequentemente aplicações críticas + +**Abordagem Recomendada:** Flows orquestrando múltiplas Crews com etapas de validação + +**Exemplos de Casos de Uso:** +- Sistemas corporativos de suporte à decisão +- Pipelines complexos de processamento de dados +- Processamento de documentos em múltiplos estágios +- Aplicações em indústrias reguladas + +## Escolhendo Entre Crews e Flows + +### Quando Escolher Crews + +Crews são ideais quando: + +1. **Você precisa de inteligência colaborativa** - Múltiplos agentes com especializações diferentes precisam trabalhar juntos +2. **O problema requer pensamento emergente** - A solução se beneficia de diferentes perspectivas e abordagens +3. **A tarefa é principalmente criativa ou analítica** - O trabalho envolve pesquisa, criação de conteúdo ou análise +4. **Você valoriza adaptabilidade mais do que estrutura rígida** - O fluxo de trabalho pode se beneficiar da autonomia dos agentes +5. **O formato da saída pode ser um pouco flexível** - Alguma variação na estrutura do resultado é aceitável + +```python +# Example: Research Crew for market analysis +from crewai import Agent, Crew, Process, Task + +# Create specialized agents +researcher = Agent( + role="Market Research Specialist", + goal="Find comprehensive market data on emerging technologies", + backstory="You are an expert at discovering market trends and gathering data." +) + +analyst = Agent( + role="Market Analyst", + goal="Analyze market data and identify key opportunities", + backstory="You excel at interpreting market data and spotting valuable insights." +) + +# Define their tasks +research_task = Task( + description="Research the current market landscape for AI-powered healthcare solutions", + expected_output="Comprehensive market data including key players, market size, and growth trends", + agent=researcher +) + +analysis_task = Task( + description="Analyze the market data and identify the top 3 investment opportunities", + expected_output="Analysis report with 3 recommended investment opportunities and rationale", + agent=analyst, + context=[research_task] +) + +# Create the crew +market_analysis_crew = Crew( + agents=[researcher, analyst], + tasks=[research_task, analysis_task], + process=Process.sequential, + verbose=True +) + +# Run the crew +result = market_analysis_crew.kickoff() +``` + +### Quando Escolher Flows + +Flows são ideais quando: + +1. **Você precisa de controle preciso da execução** - O fluxo de trabalho exige sequenciamento exato e gerenciamento de estado +2. **A aplicação tem requisitos complexos de estado** - Você precisa manter e transformar estado ao longo de múltiplas etapas +3. **Você precisa de saídas estruturadas e previsíveis** - A aplicação exige resultados consistentes e formatados +4. **O fluxo de trabalho envolve lógica condicional** - Caminhos diferentes precisam ser seguidos com base em resultados intermediários +5. **Você precisa combinar IA com código procedural** - A solução demanda tanto capacidades de IA quanto programação tradicional + +```python +# Example: Customer Support Flow with structured processing +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel +from typing import List, Dict + +# Define structured state +class SupportTicketState(BaseModel): + ticket_id: str = "" + customer_name: str = "" + issue_description: str = "" + category: str = "" + priority: str = "medium" + resolution: str = "" + satisfaction_score: int = 0 + +class CustomerSupportFlow(Flow[SupportTicketState]): + @start() + def receive_ticket(self): + # In a real app, this might come from an API + self.state.ticket_id = "TKT-12345" + self.state.customer_name = "Alex Johnson" + self.state.issue_description = "Unable to access premium features after payment" + return "Ticket received" + + @listen(receive_ticket) + def categorize_ticket(self, _): + # Use a direct LLM call for categorization + from crewai import LLM + llm = LLM(model="openai/gpt-4o-mini") + + prompt = f""" + Categorize the following customer support issue into one of these categories: + - Billing + - Account Access + - Technical Issue + - Feature Request + - Other + + Issue: {self.state.issue_description} + + Return only the category name. + """ + + self.state.category = llm.call(prompt).strip() + return self.state.category + + @router(categorize_ticket) + def route_by_category(self, category): + # Route to different handlers based on category + return category.lower().replace(" ", "_") + + @listen("billing") + def handle_billing_issue(self): + # Handle billing-specific logic + self.state.priority = "high" + # More billing-specific processing... + return "Billing issue handled" + + @listen("account_access") + def handle_access_issue(self): + # Handle access-specific logic + self.state.priority = "high" + # More access-specific processing... + return "Access issue handled" + + # Additional category handlers... + + @listen("billing", "account_access", "technical_issue", "feature_request", "other") + def resolve_ticket(self, resolution_info): + # Final resolution step + self.state.resolution = f"Issue resolved: {resolution_info}" + return self.state.resolution + +# Run the flow +support_flow = CustomerSupportFlow() +result = support_flow.kickoff() +``` + +### Quando Combinar Crews e Flows + +As aplicações mais sofisticadas frequentemente se beneficiam da combinação de Crews e Flows: + +1. **Processos complexos em múltiplos estágios** - Use Flows para orquestrar o processo geral e Crews para sub-tarefas complexas +2. **Aplicações que exigem criatividade e estrutura** - Use Crews para tarefas criativas e Flows para processamento estruturado +3. **Aplicações corporativas de IA** - Use Flows para gerenciar estado e fluxo de processo enquanto aproveita Crews para tarefas especializadas + +```python +# Example: Content Production Pipeline combining Crews and Flows +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Process, Task +from pydantic import BaseModel +from typing import List, Dict + +class ContentState(BaseModel): + topic: str = "" + target_audience: str = "" + content_type: str = "" + outline: Dict = {} + draft_content: str = "" + final_content: str = "" + seo_score: int = 0 + +class ContentProductionFlow(Flow[ContentState]): + @start() + def initialize_project(self): + # Set initial parameters + self.state.topic = "Sustainable Investing" + self.state.target_audience = "Millennial Investors" + self.state.content_type = "Blog Post" + return "Project initialized" + + @listen(initialize_project) + def create_outline(self, _): + # Use a research crew to create an outline + researcher = Agent( + role="Content Researcher", + goal=f"Research {self.state.topic} for {self.state.target_audience}", + backstory="You are an expert researcher with deep knowledge of content creation." + ) + + outliner = Agent( + role="Content Strategist", + goal=f"Create an engaging outline for a {self.state.content_type}", + backstory="You excel at structuring content for maximum engagement." + ) + + research_task = Task( + description=f"Research {self.state.topic} focusing on what would interest {self.state.target_audience}", + expected_output="Comprehensive research notes with key points and statistics", + agent=researcher + ) + + outline_task = Task( + description=f"Create an outline for a {self.state.content_type} about {self.state.topic}", + expected_output="Detailed content outline with sections and key points", + agent=outliner, + context=[research_task] + ) + + outline_crew = Crew( + agents=[researcher, outliner], + tasks=[research_task, outline_task], + process=Process.sequential, + verbose=True + ) + + # Run the crew and store the result + result = outline_crew.kickoff() + + # Parse the outline (in a real app, you might use a more robust parsing approach) + import json + try: + self.state.outline = json.loads(result.raw) + except: + # Fallback if not valid JSON + self.state.outline = {"sections": result.raw} + + return "Outline created" + + @listen(create_outline) + def write_content(self, _): + # Use a writing crew to create the content + writer = Agent( + role="Content Writer", + goal=f"Write engaging content for {self.state.target_audience}", + backstory="You are a skilled writer who creates compelling content." + ) + + editor = Agent( + role="Content Editor", + goal="Ensure content is polished, accurate, and engaging", + backstory="You have a keen eye for detail and a talent for improving content." + ) + + writing_task = Task( + description=f"Write a {self.state.content_type} about {self.state.topic} following this outline: {self.state.outline}", + expected_output="Complete draft content in markdown format", + agent=writer + ) + + editing_task = Task( + description="Edit and improve the draft content for clarity, engagement, and accuracy", + expected_output="Polished final content in markdown format", + agent=editor, + context=[writing_task] + ) + + writing_crew = Crew( + agents=[writer, editor], + tasks=[writing_task, editing_task], + process=Process.sequential, + verbose=True + ) + + # Run the crew and store the result + result = writing_crew.kickoff() + self.state.final_content = result.raw + + return "Content created" + + @listen(write_content) + def optimize_for_seo(self, _): + # Use a direct LLM call for SEO optimization + from crewai import LLM + llm = LLM(model="openai/gpt-4o-mini") + + prompt = f""" + Analyze this content for SEO effectiveness for the keyword "{self.state.topic}". + Rate it on a scale of 1-100 and provide 3 specific recommendations for improvement. + + Content: {self.state.final_content[:1000]}... (truncated for brevity) + + Format your response as JSON with the following structure: + {{ + "score": 85, + "recommendations": [ + "Recommendation 1", + "Recommendation 2", + "Recommendation 3" + ] + }} + """ + + seo_analysis = llm.call(prompt) + + # Parse the SEO analysis + import json + try: + analysis = json.loads(seo_analysis) + self.state.seo_score = analysis.get("score", 0) + return analysis + except: + self.state.seo_score = 50 + return {"score": 50, "recommendations": ["Unable to parse SEO analysis"]} + +# Run the flow +content_flow = ContentProductionFlow() +result = content_flow.kickoff() +``` + +## Framework Prático de Avaliação + +Para determinar a abordagem certa para seu caso de uso específico, siga este framework passo a passo: + +### Passo 1: Avalie a Complexidade + +Classifique a complexidade do seu aplicativo numa escala de 1-10 considerando: + +1. **Número de etapas**: Quantas operações distintas são necessárias? + - 1-3 etapas: Baixa complexidade (1-3) + - 4-7 etapas: Média complexidade (4-7) + - 8+ etapas: Alta complexidade (8-10) + +2. **Interdependências**: Quão interligadas estão as partes diferentes? + - Poucas dependências: Baixa complexidade (1-3) + - Algumas dependências: Média complexidade (4-7) + - Muitas dependências complexas: Alta complexidade (8-10) + +3. **Lógica condicional**: Quanto de ramificação e tomada de decisão é necessário? + - Processo linear: Baixa complexidade (1-3) + - Alguma ramificação: Média complexidade (4-7) + - Árvores de decisão complexas: Alta complexidade (8-10) + +4. **Conhecimento de domínio**: Quão especializado deve ser o conhecimento requerido? + - Conhecimento geral: Baixa complexidade (1-3) + - Algum conhecimento especializado: Média complexidade (4-7) + - Grande especialização em múltiplos domínios: Alta complexidade (8-10) + +Calcule a média das pontuações para determinar sua complexidade geral. + +### Passo 2: Avalie os Requisitos de Precisão + +Classifique seus requisitos de precisão numa escala de 1-10 considerando: + +1. **Estrutura da saída**: Quão estruturado o resultado deve ser? + - Texto livre: Baixa precisão (1-3) + - Semi-estruturado: Média precisão (4-7) + - Estritamente formatado (JSON, XML): Alta precisão (8-10) + +2. **Necessidade de exatidão**: Qual a importância da precisão factual? + - Conteúdo criativo: Baixa precisão (1-3) + - Conteúdo informacional: Média precisão (4-7) + - Informação crítica: Alta precisão (8-10) + +3. **Reprodutibilidade**: Quão consistentes devem ser os resultados entre execuções? + - Variação aceitável: Baixa precisão (1-3) + - Alguma consistência necessária: Média precisão (4-7) + - Exata reprodutibilidade: Alta precisão (8-10) + +4. **Tolerância a erros**: Qual o impacto de erros? + - Baixo impacto: Baixa precisão (1-3) + - Impacto moderado: Média precisão (4-7) + - Alto impacto: Alta precisão (8-10) + +Calcule a média das pontuações para determinar seu requisito geral de precisão. + +### Passo 3: Mapeie na Matriz + +Plote as pontuações de complexidade e precisão na matriz: + +- **Baixa Complexidade (1-4), Baixa Precisão (1-4)**: Crews simples +- **Baixa Complexidade (1-4), Alta Precisão (5-10)**: Flows com chamadas diretas a LLM +- **Alta Complexidade (5-10), Baixa Precisão (1-4)**: Crews complexas +- **Alta Complexidade (5-10), Alta Precisão (5-10)**: Flows orquestrando Crews + +### Passo 4: Considere Fatores Adicionais + +Além de complexidade e precisão, considere: + +1. **Tempo de desenvolvimento**: Crews costumam ser mais rápidas para prototipar +2. **Necessidades de manutenção**: Flows proporcionam melhor manutenção a longo prazo +3. **Expertise do time**: Considere a familiaridade de sua equipe com as abordagens +4. **Requisitos de escalabilidade**: Flows normalmente escalam melhor para aplicações complexas +5. **Necessidades de integração**: Considere como a solução se integrará aos sistemas existentes + +## Conclusão + +Escolher entre Crews e Flows — ou combiná-los — é uma decisão arquitetônica crítica que impacta a efetividade, manutenibilidade e escalabilidade da sua aplicação CrewAI. Ao avaliar seu caso de uso nas dimensões de complexidade e precisão, você toma decisões inteligentes que alinham-se aos seus requisitos. + +Lembre-se de que a melhor abordagem geralmente evolui na medida em que sua aplicação amadurece. Comece com a solução mais simples que atenda às suas necessidades e esteja preparado para refinar sua arquitetura conforme for ganhando experiência e seus requisitos se tornarem mais claros. + + +Agora você tem um framework para avaliar casos de uso CrewAI e escolher a abordagem certa de acordo com requisitos de complexidade e precisão. Isso vai ajudar você a construir aplicações de IA mais eficientes, de fácil manutenção e escaláveis. + + +## Próximos Passos + +- Saiba mais sobre [como criar agentes eficazes](/pt-BR/guides/agents/crafting-effective-agents) +- Explore [como construir sua primeira crew](/pt-BR/guides/crews/first-crew) +- Aprofunde-se em [gerenciamento de estado em flows](/pt-BR/guides/flows/mastering-flow-state) +- Confira os [conceitos centrais](/pt-BR/concepts/agents) para um entendimento mais aprofundado diff --git a/docs/pt-BR/guides/crews/first-crew.mdx b/docs/pt-BR/guides/crews/first-crew.mdx new file mode 100644 index 000000000..22daee040 --- /dev/null +++ b/docs/pt-BR/guides/crews/first-crew.mdx @@ -0,0 +1,392 @@ +--- +title: Monte sua Primeira Crew +description: Tutorial passo a passo para criar uma equipe colaborativa de IA que trabalha junta para resolver problemas complexos. +icon: users-gear +--- + +## Liberando o Poder da IA Colaborativa + +Imagine ter uma equipe de agentes de IA especializados trabalhando juntos de forma harmoniosa para resolver problemas complexos, cada um contribuindo com suas habilidades únicas para alcançar um objetivo comum. Esse é o poder da CrewAI – um framework que permite criar sistemas colaborativos de IA que podem realizar tarefas muito além do que uma única IA conseguiria sozinha. + +Neste guia, vamos criar uma crew de pesquisa que irá nos ajudar a pesquisar e analisar um tema, e então criar um relatório abrangente. Este exemplo prático demonstra como agentes de IA podem colaborar para realizar tarefas complexas, mas é apenas o começo do que é possível com a CrewAI. + +### O que Você Vai Construir e Aprender + +Ao final deste guia, você terá: + +1. **Criado uma equipe de pesquisa em IA especializada** com papéis e responsabilidades distintas +2. **Orquestrado a colaboração** entre múltiplos agentes de IA +3. **Automatizado um fluxo de trabalho complexo** que envolve coleta de informações, análise e geração de relatórios +4. **Desenvolvido habilidades fundamentais** que podem ser aplicadas em projetos mais ambiciosos + +Embora estejamos criando uma crew de pesquisa simples neste guia, os mesmos padrões e técnicas podem ser aplicados para criar equipes muito mais sofisticadas para tarefas como: + +- Criação de conteúdo em múltiplas etapas com redatores, editores e checadores de fatos especializados +- Sistemas de atendimento ao cliente complexos com agentes de suporte em diferentes níveis +- Analistas de negócios autônomos que coletam dados, criam visualizações e geram insights +- Equipes de desenvolvimento de produto que idealizam, projetam e planejam a implementação + +Vamos começar a construir sua primeira crew! + +### Pré-requisitos + +Antes de começar, certifique-se de que você: + +1. Instalou a CrewAI seguindo o [guia de instalação](/pt-BR/installation) +2. Configurou sua chave de API de LLM no ambiente, conforme o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm) +3. Tem conhecimento básico de Python + +## Passo 1: Crie um Novo Projeto CrewAI + +Primeiro, vamos criar um novo projeto CrewAI usando a CLI. Este comando irá configurar toda a estrutura do projeto com os arquivos necessários, permitindo que você foque em definir seus agentes e suas tarefas, em vez de se preocupar com código boilerplate. + +```bash +crewai create crew research_crew +cd research_crew +``` + +Isso irá gerar um projeto com a estrutura básica necessária para sua crew. A CLI cria automaticamente: + +- Um diretório de projeto com os arquivos necessários +- Arquivos de configuração para agentes e tarefas +- Uma implementação básica da crew +- Um script principal para rodar a crew + + + CrewAI Framework Overview + + + +## Passo 2: Explore a Estrutura do Projeto + +Vamos dedicar um momento para entender a estrutura do projeto criada pela CLI. A CrewAI segue boas práticas para projetos Python, tornando fácil manter e estender seu código à medida que suas crews se tornam mais complexas. + +``` +research_crew/ +├── .gitignore +├── pyproject.toml +├── README.md +├── .env +└── src/ + └── research_crew/ + ├── __init__.py + ├── main.py + ├── crew.py + ├── tools/ + │ ├── custom_tool.py + │ └── __init__.py + └── config/ + ├── agents.yaml + └── tasks.yaml +``` + +Esta estrutura segue as melhores práticas para projetos Python e facilita a organização do seu código. A separação dos arquivos de configuração (em YAML) do código de implementação (em Python) permite modificar o comportamento da sua crew sem alterar o código subjacente. + +## Passo 3: Configure seus Agentes + +Agora vem a parte divertida – definir seus agentes de IA! Na CrewAI, agentes são entidades especializadas com papéis, objetivos e históricos específicos que moldam seu comportamento. Pense neles como personagens em uma peça, cada um com sua personalidade e propósito próprios. + +Para nossa crew de pesquisa, vamos criar dois agentes: +1. Um **pesquisador** que é especialista em encontrar e organizar informações +2. Um **analista** que pode interpretar os resultados da pesquisa e criar relatórios perspicazes + +Vamos modificar o arquivo `agents.yaml` para definir esses agentes especializados. Certifique-se de +definir `llm` para o provedor que você está utilizando. + +```yaml +# src/research_crew/config/agents.yaml +researcher: + role: > + Especialista Sênior em Pesquisa para {topic} + goal: > + Encontrar informações abrangentes e precisas sobre {topic} + com foco em desenvolvimentos recentes e insights chave + backstory: > + Você é um especialista em pesquisa experiente com talento para + encontrar informações relevantes de diversas fontes. Você se destaca em + organizar informações de forma clara e estruturada, tornando temas complexos acessíveis para outros. + llm: provider/model-id # ex: openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude... + +analyst: + role: > + Analista de Dados e Redator de Relatórios para {topic} + goal: > + Analisar os resultados da pesquisa e criar um relatório abrangente e bem estruturado + que apresente os insights de forma clara e envolvente + backstory: > + Você é um analista habilidoso com experiência em interpretação de dados + e redação técnica. Tem talento para identificar padrões + e extrair insights relevantes dos dados de pesquisa, comunicando esses insights de forma eficaz por meio de relatórios bem elaborados. + llm: provider/model-id # ex: openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude... +``` + +Perceba como cada agente tem um papel, objetivo e histórico distintos. Esses elementos não são apenas descritivos – eles efetivamente moldam como o agente aborda suas tarefas. Ao criar cuidadosamente esses detalhes, você pode ter agentes com habilidades e perspectivas que se complementam. + +## Passo 4: Defina suas Tarefas + +Com nossos agentes definidos, agora precisamos atribuir tarefas específicas para eles realizarem. Tarefas na CrewAI representam o trabalho concreto que os agentes irão executar, com instruções detalhadas e saídas esperadas. + +Para nossa crew de pesquisa, vamos definir duas tarefas principais: +1. Uma **tarefa de pesquisa** para coletar informações abrangentes +2. Uma **tarefa de análise** para criar um relatório com insights + +Vamos modificar o arquivo `tasks.yaml`: + +```yaml +# src/research_crew/config/tasks.yaml +research_task: + description: > + Realize uma pesquisa aprofundada sobre {topic}. Foque em: + 1. Conceitos e definições chave + 2. Desenvolvimento histórico e tendências recentes + 3. Principais desafios e oportunidades + 4. Aplicações relevantes ou estudos de caso + 5. Perspectivas futuras e novos desenvolvimentos + + Certifique-se de organizar seus achados em um formato estruturado, com seções claras. + expected_output: > + Um documento de pesquisa abrangente com seções bem organizadas cobrindo + todos os aspectos solicitados de {topic}. Inclua fatos, números + e exemplos específicos sempre que possível. + agent: researcher + +analysis_task: + description: > + Analise os resultados da pesquisa e crie um relatório abrangente sobre {topic}. + Seu relatório deve: + 1. Iniciar com um resumo executivo + 2. Incluir todas as informações relevantes da pesquisa + 3. Oferecer uma análise perspicaz de tendências e padrões + 4. Apresentar recomendações ou considerações futuras + 5. Estar formatado de forma profissional, clara e com títulos bem definidos + expected_output: > + Um relatório profissional, polido e estruturado sobre {topic} com apresentação dos resultados da pesquisa, + acrescentando análise e insights. O relatório deve ser bem estruturado, + incluindo resumo executivo, sessões principais e conclusão. + agent: analyst + context: + - research_task + output_file: output/report.md +``` + +Note o campo `context` na tarefa de análise – esse é um recurso poderoso que permite ao analista acessar a saída da tarefa de pesquisa. Isso cria um fluxo de trabalho em que a informação circula naturalmente entre os agentes, como aconteceria em uma equipe humana. + +## Passo 5: Configure sua Crew + +Agora é hora de juntar tudo configurando nossa crew. A crew é o container que orquestra como os agentes trabalham juntos para completar as tarefas. + +Vamos modificar o arquivo `crew.py`: + +```python +# src/research_crew/crew.py +from crewai import Agent, Crew, Process, Task +from crewai.project import CrewBase, agent, crew, task +from crewai_tools import SerperDevTool +from crewai.agents.agent_builder.base_agent import BaseAgent +from typing import List + +@CrewBase +class ResearchCrew(): + """Research crew for comprehensive topic analysis and reporting""" + + agents: List[BaseAgent] + tasks: List[Task] + + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], # type: ignore[index] + verbose=True, + tools=[SerperDevTool()] + ) + + @agent + def analyst(self) -> Agent: + return Agent( + config=self.agents_config['analyst'], # type: ignore[index] + verbose=True + ) + + @task + def research_task(self) -> Task: + return Task( + config=self.tasks_config['research_task'] # type: ignore[index] + ) + + @task + def analysis_task(self) -> Task: + return Task( + config=self.tasks_config['analysis_task'], # type: ignore[index] + output_file='output/report.md' + ) + + @crew + def crew(self) -> Crew: + """Creates the research crew""" + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) +``` + +Neste código, estamos: +1. Criando o agente pesquisador e equipando-o com o SerperDevTool para buscas web +2. Criando o agente analista +3. Definindo as tarefas de pesquisa e análise +4. Configurando a crew para executar as tarefas sequencialmente (o analista espera o pesquisador terminar) + +É aqui que a mágica acontece – com poucas linhas de código, definimos um sistema colaborativo de IA onde agentes especializados trabalham juntos em um processo coordenado. + +## Passo 6: Prepare seu Script Principal + +Agora, vamos preparar o script principal que irá rodar nossa crew. É aqui que informamos o tema específico que queremos pesquisar. + +```python +#!/usr/bin/env python +# src/research_crew/main.py +import os +from research_crew.crew import ResearchCrew + +# Crie o diretório de saída se não existir +os.makedirs('output', exist_ok=True) + +def run(): + """ + Rodar a crew de pesquisa. + """ + inputs = { + 'topic': 'Inteligência Artificial na Saúde' + } + + # Criar e rodar a crew + result = ResearchCrew().crew().kickoff(inputs=inputs) + + # Imprimir o resultado + print("\n\n=== RELATÓRIO FINAL ===\n\n") + print(result.raw) + + print("\n\nRelatório salvo em output/report.md") + +if __name__ == "__main__": + run() +``` + +Este script prepara o ambiente, define o tema de pesquisa e inicia o trabalho da crew. O poder da CrewAI fica evidente em como esse código é simples – toda a complexidade do gerenciamento de múltiplos agentes de IA é tratada pelo framework. + +## Passo 7: Defina suas Variáveis de Ambiente + +Crie um arquivo `.env` na raiz do seu projeto com suas chaves de API: + +```sh +SERPER_API_KEY=sua_serper_api_key +# Adicione a chave de API do seu provedor também. +``` + +Confira o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm) para detalhes sobre como configurar o provedor de sua escolha. Você pode obter a chave da Serper em [Serper.dev](https://serper.dev/). + +## Passo 8: Instale as Dependências + +Instale as dependências necessárias usando a CLI da CrewAI: + +```bash +crewai install +``` + +Este comando irá: +1. Ler as dependências da configuração do seu projeto +2. Criar um ambiente virtual se necessário +3. Instalar todos os pacotes necessários + +## Passo 9: Execute sua Crew + +Agora chega o momento empolgante – é hora de rodar sua crew e assistir à colaboração de IA em ação! + +```bash +crewai run +``` + +Ao rodar esse comando, você verá sua crew ganhando vida. O pesquisador irá coletar informações sobre o tema especificado, e o analista irá criar um relatório abrangente baseado nessa pesquisa. Você poderá acompanhar em tempo real o raciocínio, as ações e os resultados dos agentes à medida que colaboram para concluir as tarefas. + +## Passo 10: Revise o Resultado + +Após a conclusão do trabalho da crew, você encontrará o relatório final em `output/report.md`. O relatório incluirá: + +1. Um resumo executivo +2. Informações detalhadas sobre o tema +3. Análises e insights +4. Recomendações ou considerações futuras + +Tire um momento para valorizar o que você realizou – você criou um sistema no qual múltiplos agentes de IA colaboraram em uma tarefa complexa, cada um contribuindo com suas habilidades especializadas para gerar um resultado maior do que qualquer agente conseguiria sozinho. + +## Explorando Outros Comandos da CLI + +A CrewAI oferece vários outros comandos úteis de CLI para trabalhar com crews: + +```bash +# Ver todos os comandos disponíveis +crewai --help + +# Rodar a crew +crewai run + +# Testar a crew +crewai test + +# Resetar as memórias da crew +crewai reset-memories + +# Repetir a partir de uma tarefa específica +crewai replay -t +``` + +## O que Mais é Possível: Além da sua Primeira Crew + +O que você construiu neste guia é só o começo. As habilidades e padrões aprendidos aqui podem ser aplicados para criar sistemas de IA cada vez mais sofisticados. Veja algumas maneiras de expandir sua crew de pesquisa básica: + +### Expandindo sua Crew + +Você pode adicionar mais agentes especializados à sua crew: +- Um **checador de fatos** para verificar as informações encontradas +- Um **visualizador de dados** para criar gráficos e tabelas +- Um **especialista de domínio** com conhecimento aprofundado em uma área específica +- Um **crítico** para identificar pontos fracos na análise + +### Adicionando Ferramentas e Capacidades + +Você pode potencializar seus agentes com ferramentas adicionais: +- Ferramentas de navegação web para pesquisa em tempo real +- Ferramentas para CSV ou bancos de dados para análise de dados +- Ferramentas de execução de código para processamento de dados +- Conexões de API com serviços externos + +### Criando Fluxos de Trabalho Mais Complexos + +Você pode implementar processos mais sofisticados: +- Processos hierárquicos em que agentes gestores delegam para agentes +- Processos iterativos com loops de feedback para refinamento +- Processos paralelos onde múltiplos agentes trabalham simultaneamente +- Processos dinâmicos que se adaptam a resultados intermediários + +### Aplicando em Diferentes Domínios + +Os mesmos padrões podem ser aplicados para criar crews para: +- **Criação de conteúdo:** Redatores, editores, checadores de fatos e designers trabalhando juntos +- **Atendimento ao cliente:** Agentes de triagem, especialistas e controle de qualidade atuando colaborativamente +- **Desenvolvimento de produto:** Pesquisadores, designers e planejadores trabalhando em conjunto +- **Análise de dados:** Coletores de dados, analistas e especialistas em visualização + +## Próximos Passos + +Agora que você montou sua primeira crew, você pode: + +1. Experimentar diferentes configurações e personalidades de agentes +2. Testar estruturas de tarefas e fluxos de trabalho mais complexos +3. Implementar ferramentas customizadas para dar novas capacidades aos agentes +4. Aplicar sua crew em outros temas ou domínios de problemas +5. Explorar [CrewAI Flows](/pt-BR/guides/flows/first-flow) para fluxos de trabalho avançados usando programação procedural + + +Parabéns! Você construiu com sucesso sua primeira crew com o CrewAI, capaz de pesquisar e analisar qualquer tema que desejar. Essa experiência fundamental lhe deu as habilidades para criar sistemas de IA cada vez mais sofisticados, aptos a encarar problemas complexos e de múltiplas etapas por meio da inteligência colaborativa. + diff --git a/docs/pt-BR/guides/flows/first-flow.mdx b/docs/pt-BR/guides/flows/first-flow.mdx new file mode 100644 index 000000000..1f299a6b2 --- /dev/null +++ b/docs/pt-BR/guides/flows/first-flow.mdx @@ -0,0 +1,461 @@ +--- +title: Construa Seu Primeiro Flow +description: Aprenda como criar fluxos de trabalho estruturados e orientados a eventos com controle preciso sobre a execução. +icon: diagram-project +--- + +## Assumindo o Controle de Workflows de IA com Flows + +Os Flows do CrewAI representam o próximo nível em orquestração de IA – combinando o poder colaborativo de equipes de agentes de IA com a precisão e flexibilidade da programação procedural. Enquanto os crews se destacam em colaboração de agentes, os flows dão a você controle detalhado sobre exatamente como e quando diferentes componentes do seu sistema de IA interagem. + +Neste guia, vamos percorrer a criação de um poderoso CrewAI Flow que gera um guia de aprendizado abrangente sobre qualquer tema. Este tutorial demonstrará como os Flows oferecem controle estruturado e orientado a eventos sobre seus workflows de IA ao combinar código regular, chamadas diretas a LLM e processamento baseado em crews. + +### O Que Torna os Flows Poderosos + +Com flows, você pode: + +1. **Combinar diferentes padrões de interação com IA** – Use crews para tarefas colaborativas complexas, chamadas diretas às LLMs para operações mais simples, e código regular para lógica procedural. +2. **Construir sistemas orientados a eventos** – Defina como os componentes respondem a eventos e mudanças de dados específicos. +3. **Manter estado entre componentes** – Compartilhe e transforme dados entre diferentes partes da sua aplicação. +4. **Integrar com sistemas externos** – Conecte seu fluxo de trabalho de IA com bancos de dados, APIs e interfaces de usuário de forma transparente. +5. **Criar caminhos de execução complexos** – Projete ramificações condicionais, processamento paralelo e workflows dinâmicos. + +### O Que Você Vai Construir e Aprender + +Ao final deste guia, você terá: + +1. **Criado um sistema sofisticado de geração de conteúdo** que combina entrada do usuário, planejamento por IA e criação de conteúdo multiagente. +2. **Orquestrado o fluxo de informações** entre diferentes componentes do seu sistema. +3. **Implementado uma arquitetura orientada a eventos** onde cada etapa responde à conclusão das etapas anteriores. +4. **Construído uma base para aplicações de IA mais complexas** que você pode expandir e personalizar. + +Este flow de criação de guia demonstra padrões fundamentais que podem ser aplicados para criar aplicações muito mais avançadas, como: + +- Assistentes de IA interativos que combinam múltiplos subsistemas especializados. +- Pipelines de processamento de dados complexos com transformações aprimoradas por IA. +- Agentes autônomos integrados a serviços e APIs externas. +- Sistemas de tomada de decisão em múltiplas etapas com processos envolvendo humanos no loop. + +Vamos começar e construir seu primeiro flow! + +## Pré-requisitos + +Antes de começar, certifique-se de ter: + +1. Instalado o CrewAI seguindo o [guia de instalação](/pt-BR/installation) +2. Configurado sua chave de API LLM no ambiente, conforme o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm) +3. Conhecimentos básicos de Python + +## Passo 1: Crie um Novo Projeto de CrewAI Flow + +Primeiro, vamos criar um novo projeto de Flow do CrewAI usando a CLI. Este comando configura um projeto com todos os diretórios necessários e arquivos de template para seu flow. + +```bash +crewai create flow guide_creator_flow +cd guide_creator_flow +``` + +Isso gerará um projeto com a estrutura básica necessária para seu flow. + + + CrewAI Framework Overview + + +## Passo 2: Entendendo a Estrutura do Projeto + +O projeto gerado possui a seguinte estrutura. Reserve um momento para conhecê-la, pois isso ajudará você a criar flows mais complexos no futuro. + +``` +guide_creator_flow/ +├── .gitignore +├── pyproject.toml +├── README.md +├── .env +├── main.py +├── crews/ +│ └── poem_crew/ +│ ├── config/ +│ │ ├── agents.yaml +│ │ └── tasks.yaml +│ └── poem_crew.py +└── tools/ + └── custom_tool.py +``` + +Esta estrutura oferece uma separação clara entre os diferentes componentes do seu flow: +- A lógica principal do flow no arquivo `main.py` +- Crews especializados no diretório `crews` +- Ferramentas customizadas no diretório `tools` + +Vamos modificar esta estrutura para criar nosso flow de criação de guias, que irá orquestrar o processo de geração de guias de aprendizagem abrangentes. + +## Passo 3: Adicione um Crew de Redator de Conteúdo + +Nosso flow precisará de um crew especializado para lidar com o processo de criação de conteúdo. Vamos usar a CLI do CrewAI para adicionar um crew de redatores de conteúdo: + +```bash +crewai flow add-crew content-crew +``` + +Este comando cria automaticamente os diretórios e arquivos de template necessários para seu crew. O crew de redatores será responsável por escrever e revisar seções do nosso guia, trabalhando dentro do flow orquestrado pela aplicação principal. + +## Passo 4: Configure o Crew de Redator de Conteúdo + +Agora, vamos modificar os arquivos gerados para o crew de redatores. Vamos configurar dois agentes especializados – um escritor e um revisor – que irão colaborar para criar um conteúdo de alta qualidade para o nosso guia. + +1. Primeiro, atualize o arquivo de configuração de agents para definir a equipe de criação de conteúdo: + + Lembre-se de configurar o `llm` com o provedor que está utilizando. + +```yaml +# src/guide_creator_flow/crews/content_crew/config/agents.yaml +content_writer: + role: > + Redator de Conteúdo Educacional + goal: > + Criar conteúdo envolvente e informativo que explique completamente o tema proposto + e forneça insights valiosos ao leitor + backstory: > + Você é um talentoso escritor educacional com experiência em criar conteúdo claro + e atraente. Você tem facilidade para explicar conceitos complexos em linguagem acessível + e organizar as informações de forma a ajudar o leitor a construir seu entendimento. + llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude... + +content_reviewer: + role: > + Revisor(a) e Editor(a) de Conteúdo Educacional + goal: > + Garantir que o conteúdo seja preciso, abrangente, bem estruturado e mantenha + consistência com as seções previamente escritas + backstory: > + Você é um editor(a) meticuloso(a) com anos de experiência revisando conteúdo educacional. + Tem atenção aos detalhes, clareza e coesão. Você se destaca em aprimorar conteúdo + mantendo o estilo do autor original e garantindo qualidade consistente em várias seções. + llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude... +``` + +Essas definições de agents estabelecem papéis e perspectivas especializadas que irão moldar como nossos agentes de IA abordam a criação de conteúdo. Note como cada agent possui um propósito e expertise distintos. + +2. Em seguida, atualize o arquivo de configuração de tarefas para definir as tarefas específicas de escrita e revisão: + +```yaml +# src/guide_creator_flow/crews/content_crew/config/tasks.yaml +write_section_task: + description: > + Escreva uma seção abrangente sobre o tema: "{section_title}" + + Descrição da seção: {section_description} + Público-alvo: {audience_level} aprendizes + + Seu conteúdo deve: + 1. Começar com uma breve introdução ao tema da seção + 2. Explicar claramente todos os conceitos principais com exemplos + 3. Incluir aplicações práticas ou exercícios onde apropriado + 4. Terminar com um resumo dos pontos principais + 5. Ter aproximadamente 500-800 palavras + + Formate seu conteúdo em Markdown com títulos, listas e ênfase apropriados. + + Seções previamente escritas: + {previous_sections} + + Certifique-se de que seu conteúdo mantenha consistência com as seções já escritas + e amplie os conceitos que já foram explicados. + expected_output: > + Uma seção bem estruturada e abrangente em formato Markdown que explique + totalmente o tema e é apropriada para o público-alvo. + agent: content_writer + +review_section_task: + description: > + Revise e melhore a seguinte seção sobre "{section_title}": + + {draft_content} + + Público-alvo: {audience_level} aprendizes + + Seções previamente escritas: + {previous_sections} + + Sua revisão deve: + 1. Corrigir qualquer erro gramatical ou de ortografia + 2. Melhorar clareza e legibilidade + 3. Garantir que o conteúdo seja abrangente e preciso + 4. Verificar a consistência com as seções já escritas + 5. Aprimorar a estrutura e o fluxo + 6. Adicionar qualquer informação-chave ausente + + Forneça a versão aprimorada da seção em formato Markdown. + expected_output: > + Uma versão melhorada e refinada da seção, mantendo a estrutura original, + mas aprimorando clareza, precisão e consistência. + agent: content_reviewer + context: + - write_section_task +``` + +Essas definições de tarefas fornecem instruções detalhadas para nossos agents, garantindo que eles produzam conteúdo que atenda aos padrões de qualidade. Observe como o parâmetro `context` na tarefa de revisão cria um fluxo onde o revisor tem acesso à produção do redator. + +3. Agora, atualize o arquivo de implementação do crew para definir como nossos agents e tasks trabalham juntos: + +```python +# src/guide_creator_flow/crews/content_crew/content_crew.py +from crewai import Agent, Crew, Process, Task +from crewai.project import CrewBase, agent, crew, task +from crewai.agents.agent_builder.base_agent import BaseAgent +from typing import List + +@CrewBase +class ContentCrew(): + """Crew de redação de conteúdo""" + + agents: List[BaseAgent] + tasks: List[Task] + + @agent + def content_writer(self) -> Agent: + return Agent( + config=self.agents_config['content_writer'], # type: ignore[index] + verbose=True + ) + + @agent + def content_reviewer(self) -> Agent: + return Agent( + config=self.agents_config['content_reviewer'], # type: ignore[index] + verbose=True + ) + + @task + def write_section_task(self) -> Task: + return Task( + config=self.tasks_config['write_section_task'] # type: ignore[index] + ) + + @task + def review_section_task(self) -> Task: + return Task( + config=self.tasks_config['review_section_task'], # type: ignore[index] + context=[self.write_section_task()] + ) + + @crew + def crew(self) -> Crew: + """Cria o crew de redação de conteúdo""" + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) +``` + +Essa definição de crew estabelece o relacionamento entre nossos agents e tasks, definindo um processo sequencial onde o redator cria o rascunho e o revisor o aprimora. Embora este crew possa funcionar de forma independente, em nosso flow ele será orquestrado como parte de um sistema maior. + +## Passo 5: Crie o Flow + +Agora vem a parte emocionante – criar o flow que irá orquestrar todo o processo de criação do guia. Aqui iremos combinar código Python regular, chamadas diretas a LLM e nosso crew de criação de conteúdo em um sistema coeso. + +Nosso flow irá: +1. Obter a entrada do usuário sobre o tema e nível do público +2. Fazer uma chamada direta à LLM para criar um roteiro estruturado do guia +3. Processar cada seção sequencialmente usando o crew de redatores +4. Combinar tudo em um documento final abrangente + +Vamos criar nosso flow no arquivo `main.py`: + +```python +# [CÓDIGO NÃO TRADUZIDO, MANTER COMO ESTÁ] +``` + +Vamos analisar o que está acontecendo neste flow: + +1. Definimos modelos Pydantic para dados estruturados, garantindo segurança de tipos e representação clara dos dados. +2. Criamos uma classe de estado para manter dados entre os diferentes passos do flow. +3. Implementamos três etapas principais para o flow: + - Obtenção da entrada do usuário com o decorator `@start()` + - Criação do roteiro do guia com uma chamada direta à LLM + - Processamento das seções com nosso crew de conteúdo +4. Usamos o decorator `@listen()` para estabelecer relações orientadas a eventos entre as etapas + +Este é o poder dos flows – combinar diferentes tipos de processamento (interação com usuário, chamadas diretas a IA, tarefas colaborativas com crews) em um sistema orientado a eventos e coeso. + +## Passo 6: Configure suas Variáveis de Ambiente + +Crie um arquivo `.env` na raiz do projeto com suas chaves de API. Veja o [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm) para detalhes sobre como configurar o provedor. + +```sh .env +OPENAI_API_KEY=sua_chave_openai +# ou +GEMINI_API_KEY=sua_chave_gemini +# ou +ANTHROPIC_API_KEY=sua_chave_anthropic +``` + +## Passo 7: Instale as Dependências + +Instale as dependências necessárias: + +```bash +crewai install +``` + +## Passo 8: Execute Seu Flow + +Agora é hora de ver seu flow em ação! Execute-o usando a CLI do CrewAI: + +```bash +crewai flow kickoff +``` + +Quando você rodar esse comando, verá seu flow ganhando vida: +1. Ele solicitará um tema e o nível do público para você +2. Criará um roteiro estruturado para o seu guia +3. Processará cada seção, com o redator e o revisor colaborando em cada uma +4. Por fim, irá compilar tudo em um guia abrangente + +Isso demonstra o poder dos flows para orquestrar processos complexos envolvendo múltiplos componentes, tanto de IA quanto não-IA. + +## Passo 9: Visualize Seu Flow + +Uma das funcionalidades mais poderosas dos flows é a possibilidade de visualizar sua estrutura: + +```bash +crewai flow plot +``` + +Isso irá criar um arquivo HTML que mostra a estrutura do seu flow, incluindo os relacionamentos entre etapas e o fluxo de dados. Essa visualização pode ser inestimável para entender e depurar flows complexos. + +## Passo 10: Revise o Resultado + +Depois que o flow finalizar, você encontrará dois arquivos no diretório `output`: + +1. `guide_outline.json`: Contém o roteiro estruturado do guia +2. `complete_guide.md`: O guia abrangente com todas as seções + +Reserve um momento para revisar esses arquivos e apreciar o que você construiu – um sistema que combina entrada do usuário, interações diretas com IA e trabalho colaborativo de agents para produzir um output complexo e de alta qualidade. + +## A Arte do Possível: Além do Seu Primeiro Flow + +O que você aprendeu neste guia é uma base para criar sistemas de IA muito mais sofisticados. Veja algumas formas de expandir este flow básico: + +### Aprimorando a Interação com o Usuário + +Você pode criar flows mais interativos com: +- Interfaces web para entrada e saída de dados +- Atualizações em tempo real de progresso +- Loops de feedback e refinamento interativos +- Interações multi-stage com o usuário + +### Adicionando Mais Etapas de Processamento + +Você pode expandir seu flow com etapas adicionais para: +- Pesquisa antes da criação do roteiro +- Geração de imagens para ilustrações +- Geração de snippets de código para guias técnicos +- Garantia de qualidade e checagem final de fatos + +### Criando Flows Mais Complexos + +Você pode implementar padrões de flow mais sofisticados: +- Ramificações condicionais com base na preferência do usuário ou tipo de conteúdo +- Processamento paralelo de seções independentes +- Loops de refinamento iterativo com feedback +- Integração a APIs e serviços externos + +### Aplicando a Diferentes Domínios + +Os mesmos padrões podem ser usados para criar flows de: +- **Narrativas interativas**: criação de histórias personalizadas com base na entrada do usuário +- **Inteligência de negócios**: processamento de dados, geração de insights e criação de relatórios +- **Desenvolvimento de produtos**: facilitação de ideação, design e planejamento +- **Sistemas educacionais**: criação de experiências de aprendizagem personalizadas + +## Principais Funcionalidades Demonstradas + +Este flow de criação de guia demonstra diversos recursos poderosos do CrewAI: + +1. **Interação com o usuário**: O flow coleta input diretamente do usuário +2. **Chamadas diretas à LLM**: Usa a classe LLM para interações eficientes e direcionadas com IA +3. **Dados estruturados com Pydantic**: Usa Pydantic para garantir segurança de tipos +4. **Processamento sequencial com contexto**: Escreve seções em ordem, fornecendo as anteriores como contexto +5. **Crews multiagentes**: Utiliza agents especializados (redator e revisor) para criação de conteúdo +6. **Gerenciamento de estado**: Mantém estado entre diferentes etapas do processo +7. **Arquitetura orientada a eventos**: Usa o decorator `@listen` para responder a eventos + +## Entendendo a Estrutura do Flow + +Vamos decompor os principais componentes dos flows para ajudá-lo a entender como construir o seu: + +### 1. Chamadas Diretas à LLM + +Flows permitem que você faça chamadas diretas a modelos de linguagem quando precisa de respostas simples e estruturadas: + +```python +llm = LLM( + model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude... + response_format=GuideOutline +) +response = llm.call(messages=messages) +``` + +Isso é mais eficiente do que usar um crew quando você precisa de um output específico e estruturado. + +### 2. Arquitetura Orientada a Eventos + +Flows usam decorators para estabelecer relações entre componentes: + +```python +@start() +def get_user_input(self): + # Primeira etapa no flow + # ... + +@listen(get_user_input) +def create_guide_outline(self, state): + # Esta roda quando get_user_input é concluída + # ... +``` + +Isso cria uma estrutura clara e declarativa para sua aplicação. + +### 3. Gerenciamento de Estado + +Flows mantêm o estado entre as etapas, facilitando o compartilhamento de dados: + +```python +class GuideCreatorState(BaseModel): + topic: str = "" + audience_level: str = "" + guide_outline: GuideOutline = None + sections_content: Dict[str, str] = {} +``` + +Isso fornece uma maneira segura e tipada de rastrear e transformar dados ao longo do flow. + +### 4. Integração com Crews + +Flows podem integrar crews para tarefas colaborativas complexas: + +```python +result = ContentCrew().crew().kickoff(inputs={ + "section_title": section.title, + # ... +}) +``` + +Assim, você usa a ferramenta certa para cada parte da aplicação – chamadas diretas para tarefas simples e crews para colaboração avançada. + +## Próximos Passos + +Agora que você construiu seu primeiro flow, pode: + +1. Experimentar estruturas e padrões mais complexos de flow +2. Testar o uso do `@router()` para criar ramificações condicionais em seus flows +3. Explorar as funções `and_` e `or_` para execuções paralelas e mais complexas +4. Conectar seu flow a APIs externas, bancos de dados ou interfaces de usuário +5. Combinar múltiplos crews especializados em um único flow + + +Parabéns! Você construiu seu primeiro CrewAI Flow que combina código regular, chamadas diretas a LLM e processamento baseado em crews para criar um guia abrangente. Essas habilidades fundamentais permitem criar aplicações de IA cada vez mais sofisticadas, capazes de resolver problemas complexos de múltiplas etapas por meio de controle procedural e inteligência colaborativa. + diff --git a/docs/pt-BR/guides/flows/mastering-flow-state.mdx b/docs/pt-BR/guides/flows/mastering-flow-state.mdx new file mode 100644 index 000000000..543e3232a --- /dev/null +++ b/docs/pt-BR/guides/flows/mastering-flow-state.mdx @@ -0,0 +1,294 @@ +--- +title: Dominando o Gerenciamento de Estado em Flows +description: Um guia abrangente sobre como gerenciar, persistir e utilizar o estado em CrewAI Flows para construir aplicações de IA robustas. +icon: diagram-project +--- + +## Entendendo o Poder do Estado em Flows + +O gerenciamento de estado é a espinha dorsal de qualquer workflow de IA sofisticado. Nos Flows da CrewAI, o sistema de estado permite manter o contexto, compartilhar dados entre etapas e construir lógicas de aplicação complexas. Dominar o gerenciamento de estado é essencial para criar aplicações de IA confiáveis, sustentáveis e poderosas. + +Este guia vai te levar por tudo o que você precisa saber sobre como gerenciar o estado em CrewAI Flows, desde conceitos básicos até técnicas avançadas, com exemplos práticos de código ao longo do conteúdo. + +### Por Que o Gerenciamento de Estado Importa + +Um gerenciamento de estado efetivo possibilita que você: + +1. **Mantenha o contexto entre as etapas de execução** – Transfira informações de forma transparente entre diferentes estágios do seu workflow +2. **Construa lógicas condicionais complexas** – Tome decisões baseadas nos dados acumulados +3. **Crie aplicações persistentes** – Salve e recupere o progresso do workflow +4. **Trate erros de forma elegante** – Implemente padrões de recuperação para aplicações mais robustas +5. **Escalone suas aplicações** – Ofereça suporte a workflows complexos com organização apropriada dos dados +6. **Habilite aplicações conversacionais** – Armazene e acesse o histórico da conversa para interações de IA com contexto + +Vamos explorar como aproveitar essas capacidades de forma eficiente. + +## Fundamentos do Gerenciamento de Estado + +### O Ciclo de Vida do Estado em um Flow + +Nos Flows da CrewAI, o estado segue um ciclo de vida previsível: + +1. **Inicialização** – Quando um flow é criado, seu estado é inicializado (como um dicionário vazio ou uma instância de modelo Pydantic) +2. **Modificação** – Os métodos do flow acessam e modificam o estado durante a execução +3. **Transmissão** – O estado é automaticamente passado entre os métodos do flow +4. **Persistência** (opcional) – O estado pode ser salvo em um armazenamento e recuperado posteriormente +5. **Conclusão** – O estado final reflete as mudanças acumuladas de todos os métodos executados + +Compreender esse ciclo de vida é crucial para projetar flows eficientes. + +### Duas Abordagens Para Gerenciar Estado + +A CrewAI oferece duas maneiras para você gerenciar o estado nos seus flows: + +1. **Estado Não Estruturado** – Usando objetos do tipo dicionário para mais flexibilidade +2. **Estado Estruturado** – Usando modelos Pydantic para segurança de tipo e validação + +Vamos analisar cada abordagem em detalhe. + +## Gerenciamento de Estado Não Estruturado + +O estado não estruturado utiliza uma abordagem semelhante a dicionários, oferecendo flexibilidade e simplicidade para aplicações diretas. + +### Como Funciona + +Com estado não estruturado: +- Você acessa o estado via `self.state`, que se comporta como um dicionário +- Pode adicionar, modificar ou remover chaves livremente a qualquer momento +- Todo o estado está disponível automaticamente para todos os métodos do flow + +### Exemplo Básico + +Veja um exemplo simples de gerenciamento de estado não estruturado: + +```python +# código não traduzido +``` + +### Quando Usar Estado Não Estruturado + +O estado não estruturado é ideal para: +- Prototipagem rápida e flows simples +- Necessidade de estado que evolui dinamicamente +- Casos onde a estrutura pode não ser conhecida antecipadamente +- Flows com requisitos de estado simples + +Embora seja flexível, o estado não estruturado não possui checagem de tipos nem validação de esquema, o que pode gerar erros em aplicações mais complexas. + +## Gerenciamento de Estado Estruturado + +O estado estruturado utiliza modelos Pydantic para definir um esquema para o estado do seu flow, provendo segurança de tipo, validação e melhor experiência de desenvolvimento. + +### Como Funciona + +Ao utilizar estado estruturado: +- Você define um modelo Pydantic que representa a estrutura do seu estado +- Passa este tipo de modelo para sua classe Flow como parâmetro de tipo +- Acessa o estado via `self.state`, que se comporta como uma instância do modelo Pydantic +- Todos os campos são validados de acordo com os tipos definidos +- O IDE oferece autocompletar e suporte à checagem de tipos + +### Exemplo Básico + +Veja como implementar o gerenciamento de estado estruturado: + +```python +# código não traduzido +``` + +### Benefícios do Estado Estruturado + +Utilizar estado estruturado traz várias vantagens: + +1. **Segurança de Tipo** – Detecte erros de tipo durante o desenvolvimento +2. **Autodocumentação** – O modelo de estado documenta claramente quais dados estão disponíveis +3. **Validação** – Validação automática de tipos de dados e restrições +4. **Suporte do IDE** – Obtenha autocompletar e documentação inline +5. **Valores Padrão** – Defina facilmente valores padrões para falta de dados + +### Quando Usar Estado Estruturado + +O estado estruturado é recomendado para: +- Flows complexos com esquemas de dados bem definidos +- Projetos em equipe com múltiplos desenvolvedores no mesmo código +- Aplicações onde a validação de dados é importante +- Flows que precisam impor tipos de dados e restrições específicas + +## O ID de Estado Automático + +Tanto estados não estruturados quanto estruturados recebem automaticamente um identificador único (UUID) para ajudar a rastrear e gerenciar instâncias de estado. + +### Como Funciona + +- Para estado não estruturado, o ID é acessível via `self.state["id"]` +- Para estado estruturado, o ID é acessível via `self.state.id` +- Este ID é gerado automaticamente ao criar o flow +- O ID permanece igual durante todo o ciclo de vida do flow +- O ID pode ser usado para rastreamento, logs e recuperação de estados persistidos + +Este UUID é útil especialmente ao implementar persistência ou monitorar múltiplas execuções de flows. + +## Atualizações Dinâmicas de Estado + +Independente de você usar estado estruturado ou não estruturado, é possível atualizar o estado dinamicamente ao longo da execução do flow. + +### Passando Dados Entre Etapas + +Métodos do flow podem retornar valores que serão passados como argumento para métodos listeners: + +```python +# código não traduzido +``` + +Esse padrão permite combinar passagem de dados direta com atualizações de estado para obter máxima flexibilidade. + +## Persistindo o Estado do Flow + +Uma das funcionalidades mais poderosas da CrewAI é a habilidade de persistir o estado do flow entre execuções. Isso habilita workflows que podem ser pausados, retomados e até recuperados após falhas. + +### O Decorador @persist() + +O decorador `@persist()` automatiza a persistência de estado, salvando o estado do flow em pontos chave da execução. + +#### Persistência em Nível de Classe + +Ao aplicar em nível de classe, `@persist()` salva o estado após cada execução de método: + +```python +# código não traduzido +``` + +#### Persistência em Nível de Método + +Para mais controle, você pode aplicar `@persist()` em métodos específicos: + +```python +# código não traduzido +``` + +## Padrões Avançados de Estado + +### Lógica Condicional Baseada no Estado + +Você pode usar o estado para implementar lógicas condicionais complexas em seus flows: + +```python +# código não traduzido +``` + +### Manipulações Complexas de Estado + +Para transformar estados complexos, você pode criar métodos dedicados: + +```python +# código não traduzido +``` + +Esse padrão de criar métodos auxiliares mantém seus métodos de flow limpos, enquanto permite manipulações complexas de estado. + +## Gerenciamento de Estado com Crews + +Um dos padrões mais poderosos na CrewAI é combinar o gerenciamento de estado do flow com a execução de crews. + +### Passando Estado para Crews + +Você pode usar o estado do flow para parametrizar crews: + +```python +# código não traduzido +``` + +### Manipulando Saídas de Crews no Estado + +Quando um crew finaliza, é possível processar sua saída e armazená-la no estado do flow: + +```python +# código não traduzido +``` + +## Boas Práticas para Gerenciamento de Estado + +### 1. Mantenha o Estado Focado + +Projete seu estado para conter somente o necessário: + +```python +# Exemplo não traduzido +``` + +### 2. Use Estado Estruturado em Flows Complexos + +À medida que seus flows evoluem em complexidade, o estado estruturado se torna cada vez mais valioso: + +```python +# Exemplo não traduzido +``` + +### 3. Documente Transições de Estado + +Para flows complexos, documente como o estado muda ao longo da execução: + +```python +# Exemplo não traduzido +``` + +### 4. Trate Erros de Estado de Forma Elegante + +Implemente tratamento de erros ao acessar o estado: + +```python +# Exemplo não traduzido +``` + +### 5. Use o Estado Para Acompanhar o Progresso + +Aproveite o estado para monitorar o progresso em flows de longa duração: + +```python +# Exemplo não traduzido +``` + +### 6. Prefira Operações Imutáveis Quando Possível + +Especialmente com estado estruturado, prefira operações imutáveis para maior clareza: + +```python +# Exemplo não traduzido +``` + +## Depurando o Estado do Flow + +### Logando Alterações no Estado + +Ao desenvolver, adicione logs para acompanhar mudanças no estado: + +```python +# Exemplo não traduzido +``` + +### Visualizando o Estado + +Você pode adicionar métodos para visualizar seu estado durante o debug: + +```python +# Exemplo não traduzido +``` + +## Conclusão + +Dominar o gerenciamento de estado em CrewAI Flows te dá poder para construir aplicações de IA sofisticadas e robustas, que mantêm contexto, tomam decisões complexas e entregam resultados consistentes. + +Seja escolhendo estado não estruturado ou estruturado, implementar boas práticas de gerenciamento de estado irá ajudar a criar flows manteníveis, extensíveis e eficazes na resolução de problemas do mundo real. + +À medida que desenvolver flows mais complexos, lembre-se de que um bom gerenciamento de estado está relacionado ao equilíbrio entre flexibilidade e estrutura, tornando seu código tanto poderoso quanto fácil de entender. + + +Agora você domina os conceitos e práticas de gerenciamento de estado em CrewAI Flows! Com este conhecimento, você pode criar workflows de IA robustos que mantêm contexto, compartilham dados entre as etapas e constroem lógicas avançadas de aplicação. + + +## Próximos Passos + +- Experimente usar estado estruturado e não estruturado em seus flows +- Teste a implementação de persistência de estado para workflows de longa duração +- Explore [como construir seu primeiro crew](/pt-BR/guides/crews/first-crew) para ver como crews e flows podem funcionar juntos +- Confira a [documentação de referência de Flow](/pt-BR/concepts/flows) para funcionalidades mais avançadas diff --git a/docs/pt-BR/installation.mdx b/docs/pt-BR/installation.mdx new file mode 100644 index 000000000..e31fa5ff7 --- /dev/null +++ b/docs/pt-BR/installation.mdx @@ -0,0 +1,200 @@ +--- +title: Instalação +description: Comece a usar o CrewAI - Instale, configure e crie seu primeiro crew de IA +icon: wrench +--- + +## Tutorial em Vídeo +Assista a este tutorial em vídeo para uma demonstração passo a passo do processo de instalação: + + + +## Tutorial em Texto + + **Requisitos de Versão do Python** + + CrewAI requer `Python >=3.10 e <3.14`. Veja como verificar sua versão: + ```bash + python3 --version + ``` + + Se você precisar atualizar o Python, acesse [python.org/downloads](https://python.org/downloads) + + +CrewAI utiliza o `uv` como ferramenta de gerenciamento de dependências e pacotes. Ele simplifica a configuração e execução do projeto, oferecendo uma experiência fluida. + +Se você ainda não instalou o `uv`, siga o **passo 1** para instalá-lo rapidamente em seu sistema, caso contrário, avance para o **passo 2**. + + + + - **No macOS/Linux:** + + Use `curl` para baixar o script e executá-lo com `sh`: + + ```shell + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + Se seu sistema não possuir `curl`, você pode usar `wget`: + + ```shell + wget -qO- https://astral.sh/uv/install.sh | sh + ``` + + - **No Windows:** + + Use `irm` para baixar o script e `iex` para executá-lo: + + ```shell + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" + ``` + Caso enfrente algum problema, consulte o [guia de instalação do UV](https://docs.astral.sh/uv/getting-started/installation/) para mais informações. + + + + - Execute o seguinte comando para instalar o CLI do `crewai`: + ```shell + uv tool install crewai + ``` + + Se aparecer um aviso relacionado ao `PATH`, execute este comando para atualizar seu shell: + ```shell + uv tool update-shell + ``` + + + + Se você encontrar o erro de build ao instalar `chroma-hnswlib==0.7.6` (`fatal error C1083: Cannot open include file: 'float.h'`) no Windows, instale o (Visual Studio Build Tools)[https://visualstudio.microsoft.com/downloads/] com o *Desenvolvimento de Desktop com C++*. + + + - Para verificar se o `crewai` está instalado, execute: + ```shell + uv tool list + ``` + - Você deverá ver algo assim: + ```shell + crewai v0.102.0 + - crewai + ``` + - Caso precise atualizar o `crewai`, execute: + ```shell + uv tool install crewai --upgrade + ``` + Instalação realizada com sucesso! Você está pronto para criar seu primeiro crew! 🎉 + + + +# Criando um Projeto CrewAI + +Recomendamos utilizar o template de scaffolding `YAML` para uma abordagem estruturada na definição dos agentes e tarefas. Veja como começar: + + + + - Execute o comando CLI do `crewai`: + ```shell + crewai create crew + ``` + + - Isso criará um novo projeto com a seguinte estrutura: + + ``` + my_project/ + ├── .gitignore + ├── knowledge/ + ├── pyproject.toml + ├── README.md + ├── .env + └── src/ + └── my_project/ + ├── __init__.py + ├── main.py + ├── crew.py + ├── tools/ + │ ├── custom_tool.py + │ └── __init__.py + └── config/ + ├── agents.yaml + └── tasks.yaml + ``` + + + + + - Seu projeto conterá estes arquivos essenciais: + | Arquivo | Finalidade | + | --- | --- | + | `agents.yaml` | Defina seus agentes de IA e seus papéis | + | `tasks.yaml` | Configure as tarefas e fluxos de trabalho dos agentes | + | `.env` | Armazene chaves de API e variáveis de ambiente | + | `main.py` | Ponto de entrada e fluxo de execução do projeto | + | `crew.py` | Orquestração e coordenação do crew | + | `tools/` | Diretório para ferramentas customizadas dos agentes | + | `knowledge/` | Diretório para base de conhecimento | + + - Comece editando `agents.yaml` e `tasks.yaml` para definir o comportamento do seu crew. + - Mantenha informações sensíveis como chaves de API no arquivo `.env`. + + + + - Antes de rodar seu crew, execute: + ```bash + crewai install + ``` + - Se precisar instalar pacotes adicionais, utilize: + ```shell + uv add + ``` + - Para rodar seu crew, execute o seguinte comando na raiz do seu projeto: + ```bash + crewai run + ``` + + + +## Opções de Instalação Enterprise + + +Para equipes e organizações, o CrewAI oferece opções de implantação corporativa que eliminam a complexidade da configuração: + +### CrewAI Enterprise (SaaS) +- Zero instalação necessária - basta se cadastrar gratuitamente em [app.crewai.com](https://app.crewai.com) +- Atualizações e manutenção automáticas +- Infraestrutura e escalabilidade gerenciadas +- Construa crews sem código + +### CrewAI Factory (Auto-Hospedado) +- Implantação containerizada para sua infraestrutura +- Compatível com qualquer hyperscaler, incluindo ambientes on-premises +- Integração com seus sistemas de segurança existentes + + + Saiba mais sobre as soluções enterprise do CrewAI e agende uma demonstração + + + +## Próximos Passos + + + + Siga nosso guia de início rápido para criar seu primeiro agente CrewAI e obter experiência prática. + + + Conecte-se com outros desenvolvedores, obtenha ajuda e compartilhe suas experiências com o CrewAI. + + diff --git a/docs/pt-BR/introduction.mdx b/docs/pt-BR/introduction.mdx new file mode 100644 index 000000000..396b82360 --- /dev/null +++ b/docs/pt-BR/introduction.mdx @@ -0,0 +1,164 @@ +--- +title: Introdução +description: Construa equipes de agentes de IA que trabalham juntas para resolver tarefas complexas +icon: handshake +--- + +# O que é CrewAI? + +**CrewAI é um framework Python enxuto e ultrarrápido, construído totalmente do zero—completamente independente do LangChain ou de outros frameworks de agentes.** + +O CrewAI capacita desenvolvedores tanto com simplicidade de alto nível quanto com controle detalhado de baixo nível, ideal para criar agentes de IA autônomos sob medida para qualquer cenário: + +- **[Crews do CrewAI](/pt-BR/guides/crews/first-crew)**: Otimizados para autonomia e inteligência colaborativa, permitindo criar equipes de IA onde cada agente possui funções, ferramentas e objetivos específicos. +- **[Flows do CrewAI](/pt-BR/guides/flows/first-flow)**: Proporcionam controle granular, orientado por eventos, com chamadas LLM individuais para uma orquestração precisa das tarefas, além de suportar Crews nativamente. + +Com mais de 100.000 desenvolvedores certificados em nossos cursos comunitários, o CrewAI está se tornando rapidamente o padrão para automação de IA pronta para empresas. + + +## Como funcionam os Crews + + + Assim como uma empresa possui departamentos (Vendas, Engenharia, Marketing) trabalhando juntos sob uma liderança para atingir objetivos de negócio, o CrewAI ajuda você a criar uma “organização” de agentes de IA com funções especializadas colaborando para realizar tarefas complexas. + + + + Visão Geral do Framework CrewAI + + +| Componente | Descrição | Principais Funcionalidades | +|:-----------|:-----------:|:-------------------------| +| **Crew** | Organização de mais alto nível | • Gerencia equipes de agentes de IA
• Supervisiona fluxos de trabalho
• Garante colaboração
• Entrega resultados | +| **Agentes de IA** | Membros especializados da equipe | • Possuem funções específicas (pesquisador, escritor)
• Utilizam ferramentas designadas
• Podem delegar tarefas
• Tomam decisões autônomas | +| **Process** | Sistema de gestão do fluxo de trabalho | • Define padrões de colaboração
• Controla designação de tarefas
• Gerencia interações
• Garante execução eficiente | +| **Tasks** | Atribuições individuais | • Objetivos claros
• Utilizam ferramentas específicas
• Alimentam processos maiores
• Geram resultados acionáveis | + +### Como tudo trabalha junto + +1. O **Crew** organiza toda a operação +2. **Agentes de IA** realizam tarefas especializadas +3. O **Process** garante colaboração fluida +4. **Tasks** são concluídas para alcançar o objetivo + +## Principais Funcionalidades + + + + Crie agentes especializados com funções, conhecimentos e objetivos definidos – de pesquisadores e analistas a escritores + + + Equipe os agentes com ferramentas e APIs personalizadas para interagir com serviços e fontes de dados externas + + + Agentes trabalham juntos, compartilhando insights e coordenando tarefas para conquistar objetivos complexos + + + Defina fluxos de trabalho sequenciais ou paralelos, com agentes lidando automaticamente com dependências entre tarefas + + + +## Como funcionam os Flows + + + Enquanto Crews se destacam na colaboração autônoma, Flows proporcionam automações estruturadas, oferecendo controle granular sobre a execução dos fluxos de trabalho. Flows garantem execução confiável, segura e eficiente, lidando com lógica condicional, loops e gerenciamento dinâmico de estados com precisão. Flows se integram perfeitamente com Crews, permitindo equilibrar alta autonomia com controle rigoroso. + + + + Visão Geral do Framework CrewAI + + +| Componente | Descrição | Principais Funcionalidades | +|:-----------|:-----------:|:-------------------------| +| **Flow** | Orquestração de fluxo de trabalho estruturada | • Gerencia caminhos de execução
• Lida com transições de estado
• Controla a sequência de tarefas
• Garante execução confiável | +| **Events** | Gatilhos para ações nos fluxos | • Iniciam processos específicos
• Permitem respostas dinâmicas
• Suportam ramificações condicionais
• Adaptam-se em tempo real | +| **States** | Contextos de execução dos fluxos | • Mantêm dados de execução
• Permitem persistência
• Suportam retomada
• Garantem integridade na execução | +| **Crew Support** | Aprimora automação de fluxos | • Injeta autonomia quando necessário
• Complementa fluxos estruturados
• Equilibra automação e inteligência
• Permite tomada de decisão adaptativa | + +### Capacidades-Chave + + + + Defina caminhos de execução precisos respondendo dinamicamente a eventos + + + Gerencie estados de fluxo de trabalho e execução condicional de forma segura e eficiente + + + Combine de forma simples com Crews para maior autonomia e inteligência + + + Garanta resultados previsíveis com controle explícito de fluxo e tratamento de erros + + + +## Quando usar Crews versus Flows + + + Entender quando utilizar [Crews](/pt-BR/guides/crews/first-crew) ou [Flows](/pt-BR/guides/flows/first-flow) é fundamental para maximizar o potencial do CrewAI em suas aplicações. + + +| Caso de uso | Abordagem recomendada | Por quê? | +|:------------|:---------------------|:---------| +| **Pesquisa aberta** | [Crews](/pt-BR/guides/crews/first-crew) | Quando as tarefas exigem criatividade, exploração e adaptação | +| **Geração de conteúdo** | [Crews](/pt-BR/guides/crews/first-crew) | Para criação colaborativa de artigos, relatórios ou materiais de marketing | +| **Fluxos de decisão** | [Flows](/pt-BR/guides/flows/first-flow) | Quando é necessário caminhos de decisão previsíveis, auditáveis e com controle preciso | +| **Orquestração de APIs** | [Flows](/pt-BR/guides/flows/first-flow) | Para integração confiável com múltiplos serviços externos em sequência específica | +| **Aplicações híbridas** | Abordagem combinada | Use [Flows](/pt-BR/guides/flows/first-flow) para orquestrar o processo geral com [Crews](/pt-BR/guides/crews/first-crew) lidando com subtarefas complexas | + +### Framework de Decisão + +- **Escolha [Crews](/pt-BR/guides/crews/first-crew) quando:** Precisa de resolução autônoma de problemas, colaboração criativa ou tarefas exploratórias +- **Escolha [Flows](/pt-BR/guides/flows/first-flow) quando:** Requer resultados determinísticos, auditabilidade ou controle preciso sobre a execução +- **Combine ambos quando:** Sua aplicação precisa de processos estruturados e também de bolsões de inteligência autônoma + +## Por que escolher o CrewAI? + +- 🧠 **Operação Autônoma**: Agentes tomam decisões inteligentes com base em suas funções e nas ferramentas disponíveis +- 📝 **Interação Natural**: Agentes se comunicam e colaboram como membros humanos de uma equipe +- 🛠️ **Design Extensível**: Fácil de adicionar novas ferramentas, funções e capacidades +- 🚀 **Pronto para Produção**: Construído para confiabilidade e escalabilidade em aplicações reais +- 🔒 **Foco em Segurança**: Desenvolvido para atender requisitos de segurança empresarial +- 💰 **Custo-Efetivo**: Otimizado para minimizar o uso de tokens e chamadas de API + +## Pronto para começar a construir? + + + + Tutorial passo a passo para criar uma equipe de IA colaborativa que trabalha junto para resolver problemas complexos. + + + Aprenda a criar fluxos de trabalho estruturados e orientados por eventos com controle preciso de execução. + + + + + + Comece a usar o CrewAI em seu ambiente de desenvolvimento. + + + Siga nosso guia rápido para criar seu primeiro agente CrewAI e colocar a mão na massa. + + + Conecte-se com outros desenvolvedores, obtenha ajuda e compartilhe suas experiências com o CrewAI. + + diff --git a/docs/pt-BR/learn/before-and-after-kickoff-hooks.mdx b/docs/pt-BR/learn/before-and-after-kickoff-hooks.mdx new file mode 100644 index 000000000..6e9e520bf --- /dev/null +++ b/docs/pt-BR/learn/before-and-after-kickoff-hooks.mdx @@ -0,0 +1,60 @@ +--- +title: Hooks Antes e Depois do Kickoff +description: Aprenda a usar hooks antes e depois do kickoff em CrewAI +--- + +O CrewAI fornece hooks que permitem executar código antes e depois do kickoff de uma crew. Esses hooks são úteis para pré-processar entradas ou pós-processar resultados. + +## Hook Antes do Kickoff + +O hook antes do kickoff é executado antes da crew iniciar suas tarefas. Ele recebe o dicionário de entradas e pode modificá-lo antes de passá-lo para a crew. Você pode usar esse hook para configurar seu ambiente, carregar dados necessários ou pré-processar suas entradas. Isso é útil em cenários onde os dados de entrada podem precisar de enriquecimento ou validação antes de serem processados pela crew. + +Aqui está um exemplo de como definir uma função antes do kickoff em seu `crew.py`: + +```python +from crewai import CrewBase +from crewai.project import before_kickoff + +@CrewBase +class MyCrew: + @before_kickoff + def prepare_data(self, inputs): + # Preprocess or modify inputs + inputs['processed'] = True + return inputs + +#... +``` + +Neste exemplo, a função prepare_data modifica as entradas adicionando um novo par chave-valor indicando que as entradas foram processadas. + +## Hook Depois do Kickoff + +O hook depois do kickoff é executado após a crew completar suas tarefas. Ele recebe o objeto de resultado, que contém as saídas da execução da crew. Este hook é ideal para pós-processar resultados, como log, transformação de dados ou análise adicional. + +Veja como você pode definir uma função depois do kickoff em seu `crew.py`: + +```python +from crewai import CrewBase +from crewai.project import after_kickoff + +@CrewBase +class MyCrew: + @after_kickoff + def log_results(self, result): + # Log or modify the results + print("Crew execution completed with result:", result) + return result + +# ... +``` + +Na função `log_results`, os resultados da execução da crew são simplesmente impressos. Você pode estender isso para realizar operações mais complexas, como enviar notificações ou integrar com outros serviços. + +## Utilizando Ambos os Hooks + +Ambos os hooks podem ser usados juntos para oferecer um processo completo de preparação e finalização na execução da sua crew. Eles são particularmente úteis para manter uma arquitetura de código limpa, separando responsabilidades e melhorando a modularidade das suas implementações com CrewAI. + +## Conclusão + +Os hooks antes e depois do kickoff em CrewAI oferecem formas poderosas de interagir com o ciclo de vida da execução de uma crew. Ao entender e utilizar esses hooks, você pode aumentar significativamente a robustez e flexibilidade dos seus agentes de IA. \ No newline at end of file diff --git a/docs/pt-BR/learn/bring-your-own-agent.mdx b/docs/pt-BR/learn/bring-your-own-agent.mdx new file mode 100644 index 000000000..452e27133 --- /dev/null +++ b/docs/pt-BR/learn/bring-your-own-agent.mdx @@ -0,0 +1,441 @@ +--- +title: Traga seu próprio agente +description: Aprenda como trazer seus próprios agentes que funcionam dentro de uma Crew. +icon: robots +--- + +Interoperabilidade é um conceito fundamental no CrewAI. Este guia mostrará como trazer seus próprios agentes para funcionar dentro de uma Crew. + +## Guia de Adaptação para trazer seus próprios agentes (Agentes Langgraph, Agentes OpenAI, etc...) +Requeremos 3 adaptadores para tornar qualquer agente de diferentes frameworks compatível com uma crew. + +1. BaseAgentAdapter +2. BaseToolAdapter +3. BaseConverter + +## BaseAgentAdapter +Esta classe abstrata define a interface comum e a funcionalidade que todos +os adaptadores de agente devem implementar. Ela estende BaseAgent para manter compatibilidade +com o framework CrewAI, ao mesmo tempo em que adiciona requisitos específicos do adaptador. + +Métodos obrigatórios: + +1. `def configure_tools` +2. `def configure_structured_output` + +## Criando seu próprio Adaptador +Para integrar um agente de um framework diferente (por exemplo, LangGraph, Autogen, OpenAI Assistants) ao CrewAI, você precisa criar um adaptador customizado herdando de `BaseAgentAdapter`. Esse adaptador atua como uma camada de compatibilidade, traduzindo entre as interfaces do CrewAI e os requisitos específicos do seu agente externo. + +Veja como implementar seu adaptador customizado: + +1. **Herdar de `BaseAgentAdapter`**: + ```python + from crewai.agents.agent_adapters.base_agent_adapter import BaseAgentAdapter + from crewai.tools import BaseTool + from typing import List, Optional, Any, Dict + + class MyCustomAgentAdapter(BaseAgentAdapter): + # ... detalhes da implementação ... + ``` + +2. **Implementar `__init__`**: + O construtor deve chamar o construtor da classe pai `super().__init__(**kwargs)` e executar qualquer inicialização específica do seu agente externo. Você pode usar o dicionário opcional `agent_config` passado durante a inicialização do `Agent` do CrewAI para configurar seu adaptador e o agente subjacente. + + ```python + def __init__(self, agent_config: Optional[Dict[str, Any]] = None, **kwargs: Any): + super().__init__(agent_config=agent_config, **kwargs) + # Inicialize seu agente externo aqui, possivelmente usando agent_config + # Exemplo: self.external_agent = initialize_my_agent(agent_config) + print(f"Inicializando MyCustomAgentAdapter com config: {agent_config}") + ``` + +3. **Implementar `configure_tools`**: + Este método abstrato é crucial. Ele recebe uma lista de instâncias de `BaseTool` do CrewAI. Sua implementação deve converter ou adaptar essas ferramentas para o formato esperado pelo seu framework de agente externo. Isso pode envolver encapsulamento, extração de atributos específicos ou registro delas na instância do agente externo. + + ```python + def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None: + if tools: + adapted_tools = [] + for tool in tools: + # Adapte o CrewAI BaseTool para o formato que seu agente espera + # Exemplo: adapted_tool = adapt_to_my_framework(tool) + # adapted_tools.append(adapted_tool) + pass # Substitua pela sua lógica real de adaptação + + # Configure o agente externo com as ferramentas adaptadas + # Exemplo: self.external_agent.set_tools(adapted_tools) + print(f"Configurando ferramentas para MyCustomAgentAdapter: {adapted_tools}") # Placeholder + else: + # Caso nenhum ferramenta seja fornecida + # Exemplo: self.external_agent.set_tools([]) + print("Nenhuma ferramenta fornecida para MyCustomAgentAdapter.") + ``` + +4. **Implementar `configure_structured_output`**: + Esse método é chamado quando o `Agent` do CrewAI é configurado com requisitos de saída estruturada (por exemplo, `output_json` ou `output_pydantic`). Seu adaptador precisa garantir que o agente externo esteja configurado para cumprir esses requisitos. Isso pode envolver definir parâmetros específicos no agente externo ou garantir que seu modelo subjacente suporte o formato solicitado. Se o agente externo não suportar saída estruturada de forma compatível com as expectativas do CrewAI, talvez seja necessário lidar com a conversão ou lançar um erro apropriado. + + ```python + def configure_structured_output(self, structured_output: Any) -> None: + # Configure seu agente externo para produzir saída no formato especificado + # Exemplo: self.external_agent.set_output_format(structured_output) + self.adapted_structured_output = True # Sinaliza que a saída estruturada foi tratada + print(f"Configurando saída estruturada para MyCustomAgentAdapter: {structured_output}") + ``` + +Implementando esses métodos, seu `MyCustomAgentAdapter` permitirá que sua implementação personalizada de agente funcione corretamente dentro de uma crew do CrewAI, interagindo com tarefas e ferramentas de forma transparente. Lembre-se de substituir os comentários e prints de exemplo pela sua lógica real de adaptação específica do framework externo que está integrando. + +## Implementação de BaseToolAdapter +A classe `BaseToolAdapter` é responsável por converter os objetos nativos `BaseTool` do CrewAI em um formato que o seu framework de agente externo possa entender e utilizar. Diferentes frameworks de agentes (como LangGraph, OpenAI Assistants, etc.) possuem suas próprias formas de definir e tratar ferramentas, e o `BaseToolAdapter` age como tradutor. + +Veja como implementar seu adaptador de ferramentas personalizado: + +1. **Herdar de `BaseToolAdapter`**: + ```python + from crewai.agents.agent_adapters.base_tool_adapter import BaseToolAdapter + from crewai.tools import BaseTool + from typing import List, Any + + class MyCustomToolAdapter(BaseToolAdapter): + # ... detalhes da implementação ... + ``` + +2. **Implementar `configure_tools`**: + Este é o método abstrato principal que você deve implementar. Ele recebe uma lista de instâncias de `BaseTool` fornecidas ao agente. Sua tarefa é iterar por essa lista, adaptar cada `BaseTool` para o formato esperado pelo seu framework externo e armazenar as ferramentas convertidas na lista `self.converted_tools` (inicializada no construtor da classe base). + + ```python + def configure_tools(self, tools: List[BaseTool]) -> None: + """Configura e converte ferramentas do CrewAI para a implementação específica.""" + self.converted_tools = [] # Reseta caso seja chamado múltiplas vezes + for tool in tools: + # Sanitizar o nome da ferramenta se necessário pelo framework alvo + sanitized_name = self.sanitize_tool_name(tool.name) + + # --- Sua lógica de conversão aqui --- + # Exemplo: Converter BaseTool para formato de dicionário para LangGraph + # converted_tool = { + # "name": sanitized_name, + # "description": tool.description, + # "parameters": tool.args_schema.schema() if tool.args_schema else {}, + # # Adicione outros campos específicos do framework + # } + + # Exemplo: Converter BaseTool para definição de função OpenAI + # converted_tool = { + # "type": "function", + # "function": { + # "name": sanitized_name, + # "description": tool.description, + # "parameters": tool.args_schema.schema() if tool.args_schema else {"type": "object", "properties": {}}, + # } + # } + + # --- Substitua os exemplos acima pela sua adaptação real --- + converted_tool = self.adapt_tool_to_my_framework(tool, sanitized_name) # Placeholder + + self.converted_tools.append(converted_tool) + print(f"Ferramenta '{tool.name}' adaptada para '{sanitized_name}' em MyCustomToolAdapter") # Placeholder + + print(f"MyCustomToolAdapter terminou de configurar ferramentas: {len(self.converted_tools)} adaptadas.") # Placeholder + + # --- Método auxiliar para adaptação (Exemplo) --- + def adapt_tool_to_my_framework(self, tool: BaseTool, sanitized_name: str) -> Any: + # Substitua pela lógica real para converter um CrewAI BaseTool + # para o formato necessário do framework de agente externo específico. + # Isso pode variar bastante de acordo com o framework. + adapted_representation = { + "framework_specific_name": sanitized_name, + "framework_specific_description": tool.description, + "inputs": tool.args_schema.schema() if tool.args_schema else None, + "implementation_reference": tool.run # Ou conforme o framework precisa chamar + } + # Certifique-se também que a ferramenta funcione tanto síncrona quanto assincronamente + async def async_tool_wrapper(*args, **kwargs): + output = tool.run(*args, **kwargs) + if inspect.isawaitable(output): + return await output + else: + return output + + adapted_tool = MyFrameworkTool( + name=sanitized_name, + description=tool.description, + inputs=tool.args_schema.schema() if tool.args_schema else None, + implementation_reference=async_tool_wrapper + ) + + return adapted_representation + + ``` + +3. **Utilizando o Adaptador**: + Normalmente, você instanciaria seu `MyCustomToolAdapter` dentro do método `configure_tools` do seu `MyCustomAgentAdapter` e o usaria para processar as ferramentas antes de configurar o agente externo. + + ```python + # Dentro de MyCustomAgentAdapter.configure_tools + def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None: + if tools: + tool_adapter = MyCustomToolAdapter() # Instancia seu adaptador de ferramenta + tool_adapter.configure_tools(tools) # Converte as ferramentas + adapted_tools = tool_adapter.tools() # Obtém as ferramentas convertidas + + # Agora configure seu agente externo com as ferramentas adaptadas + # Exemplo: self.external_agent.set_tools(adapted_tools) + print(f"Configurando agente externo com ferramentas adaptadas: {adapted_tools}") # Placeholder + else: + # Caso sem ferramentas + print("Nenhuma ferramenta fornecida para MyCustomAgentAdapter.") + ``` + +Ao criar um `BaseToolAdapter`, você desacopla a lógica de conversão de ferramenta da adaptação de agente, tornando a integração mais limpa e modular. Lembre-se de substituir os exemplos de placeholder pela lógica de conversão real exigida pelo seu framework externo específico. + +## BaseConverter +O `BaseConverterAdapter` desempenha um papel crucial quando uma `Task` do CrewAI exige que um agente retorne sua saída final em um formato estruturado específico, como JSON ou um modelo Pydantic. Ele faz a ponte entre os requisitos de saída estruturada do CrewAI e as capacidades do seu agente externo. + +Suas responsabilidades principais são: +1. **Configurar o Agente para Saída Estruturada:** Com base nos requisitos da `Task` (`output_json` ou `output_pydantic`), ele instrui o `BaseAgentAdapter` associado (e indiretamente, o agente externo) sobre qual formato é esperado. +2. **Apriorar o Prompt do Sistema:** Ele modifica o prompt do sistema do agente para incluir instruções claras sobre *como* gerar a saída na estrutura exigida. +3. **Pós-processamento do Resultado:** Pega a saída bruta do agente e tenta fazer parsing, validar e formatar conforme a estrutura requerida, retornando por fim uma representação em string (por exemplo, uma string JSON). + +Veja como implementar seu adaptador de conversão customizado: + +1. **Herdar de `BaseConverterAdapter`**: + ```python + from crewai.agents.agent_adapters.base_converter_adapter import BaseConverterAdapter + # Supondo que o seu MyCustomAgentAdapter foi definido + # from .my_custom_agent_adapter import MyCustomAgentAdapter + from crewai.task import Task + from typing import Any + + class MyCustomConverterAdapter(BaseConverterAdapter): + # Armazena o tipo de saída esperado (ex: 'json', 'pydantic', 'text') + _output_type: str = 'text' + _output_schema: Any = None # Armazena o schema JSON ou modelo Pydantic + + # ... detalhes da implementação ... + ``` + +2. **Implementar `__init__`**: + O construtor deve aceitar a instância correspondente de `agent_adapter` com a qual irá trabalhar. + + ```python + def __init__(self, agent_adapter: Any): # Use um type hint específico para seu AgentAdapter + self.agent_adapter = agent_adapter + print(f"Inicializando MyCustomConverterAdapter para o adaptador de agente: {type(agent_adapter).__name__}") + ``` + +3. **Implementar `configure_structured_output`**: + Esse método recebe o objeto `Task` do CrewAI. Você precisa checar os atributos `output_json` e `output_pydantic` da task para determinar a estrutura de saída exigida. Armazene essa informação (por exemplo, em `_output_type` e `_output_schema`) e, potencialmente, chame métodos de configuração no seu `self.agent_adapter` se o agente externo necessitar de um ajuste específico para saída estruturada (algo que pode já ter sido parcialmente feito no `configure_structured_output` do adaptador de agente). + + ```python + def configure_structured_output(self, task: Task) -> None: + """Configura a saída estruturada esperada baseada na task.""" + if task.output_pydantic: + self._output_type = 'pydantic' + self._output_schema = task.output_pydantic + print(f"Converter: Configurado para saída Pydantic: {self._output_schema.__name__}") + elif task.output_json: + self._output_type = 'json' + self._output_schema = task.output_json + print(f"Converter: Configurado para saída JSON com schema: {self._output_schema}") + else: + self._output_type = 'text' + self._output_schema = None + print("Converter: Configurado para saída de texto padrão.") + + # Opcionalmente, informe o agent_adapter se necessário + # self.agent_adapter.set_output_mode(self._output_type, self._output_schema) + ``` + +4. **Implementar `enhance_system_prompt`**: + Este método recebe o prompt base do sistema do agente e deve anexar instruções adaptadas para o `_output_type` e `_output_schema` atualmente configurados. O objetivo é guiar o LLM que alimenta o agente a produzir saída no formato correto. + + ```python + def enhance_system_prompt(self, base_prompt: str) -> str: + """Aprimore o prompt do sistema com instruções de saída estruturada.""" + if self._output_type == 'text': + return base_prompt # Nenhum aprimoramento necessário para texto puro + + instructions = "\n\nSua resposta final DEVE estar formatada como " + if self._output_type == 'json': + schema_str = json.dumps(self._output_schema, indent=2) + instructions += f"um objeto JSON conforme o seguinte schema:\n```json\n{schema_str}\n```" + elif self._output_type == 'pydantic': + schema_str = json.dumps(self._output_schema.model_json_schema(), indent=2) + instructions += f"um objeto JSON conforme o modelo Pydantic '{self._output_schema.__name__}' com o seguinte schema:\n```json\n{schema_str}\n```" + + instructions += "\nGaranta que toda a sua resposta seja APENAS o objeto JSON válido, sem nenhum texto introdutório, explicações ou considerações finais." + + print(f"Converter: Aprimorando prompt para saída {self._output_type}.") + return base_prompt + instructions + ``` + *Nota: O prompt pode precisar de ajustes conforme o agente/LLM usado.* + +5. **Implementar `post_process_result`**: + Esse método recebe a saída em string bruta do agente. Se uma saída estruturada foi solicitada (`json` ou `pydantic`), você deve tentar convertê-la para o formato esperado. Trate erros de parsing caso ocorram (por exemplo, registre-os, tente corrigir, ou lance uma exceção). O método **deve sempre retornar uma string**, mesmo se o formato intermediário seja um dicionário ou objeto Pydantic (por exemplo, serializando novamente para JSON). + + ```python + import json + from pydantic import ValidationError + + def post_process_result(self, result: str) -> str: + """Pós-processa o resultado do agente para garantir que corresponde ao formato esperado.""" + print(f"Converter: Pós-processando resultado para saída {self._output_type}.") + if self._output_type == 'json': + try: + # Tenta fazer parsing e re-serializar para garantir validade e formato consistente + parsed_json = json.loads(result) + # Opcional: Validar contra o schema se for um dicionário JSON schema + # from jsonschema import validate + # validate(instance=parsed_json, schema=self._output_schema) + return json.dumps(parsed_json) + except json.JSONDecodeError as e: + print(f"Erro: Falha ao fazer parsing da saída JSON: {e}\nSaída bruta:\n{result}") + # Trate o erro: retorne bruto, lance exceção, ou tente corrigir + return result # Exemplo: retorna a saída bruta caso falhe + # except Exception as e: # Captura erros de validação se usar jsonschema + # print(f"Erro: saída JSON falhou na validação do schema: {e}\nSaída bruta:\n{result}") + # return result + elif self._output_type == 'pydantic': + try: + # Tenta fazer parsing para o modelo Pydantic + model_instance = self._output_schema.model_validate_json(result) + # Retorna o modelo serializado de volta para JSON + return model_instance.model_dump_json() + except ValidationError as e: + print(f"Erro: Falha ao validar saída Pydantic: {e}\nSaída bruta:\n{result}") + # Trate o erro + return result # Exemplo: retorna a saída bruta caso falhe + except json.JSONDecodeError as e: + print(f"Erro: Falha ao fazer parsing do JSON para o modelo Pydantic: {e}\nSaída bruta:\n{result}") + return result + else: # 'text' + return result # Sem processamento para texto puro + ``` + +Implementando esses métodos, seu `MyCustomConverterAdapter` assegurará que as solicitações de saída estruturada das tarefas do CrewAI sejam corretamente tratadas pelo seu agente externo integrado, aumentando a confiabilidade e a usabilidade do seu agente customizado dentro do framework CrewAI. + +## Adapters prontos para uso + +Fornecemos adapters prontos para uso para os seguintes frameworks: +1. LangGraph +2. Agentes OpenAI + +## Iniciando uma crew com agentes adaptados: + +```python +import json +import os +from typing import List + +from crewai_tools import SerperDevTool +from src.crewai import Agent, Crew, Task +from langchain_openai import ChatOpenAI +from pydantic import BaseModel + +from crewai.agents.agent_adapters.langgraph.langgraph_adapter import ( + LangGraphAgentAdapter, +) +from crewai.agents.agent_adapters.openai_agents.openai_adapter import OpenAIAgentAdapter + +# Agente CrewAI +code_helper_agent = Agent( + role="Code Helper", + goal="Help users solve coding problems effectively and provide clear explanations.", + backstory="You are an experienced programmer with deep knowledge across multiple programming languages and frameworks. You specialize in solving complex coding challenges and explaining solutions clearly.", + allow_delegation=False, + verbose=True, +) +# OpenAI Agent Adapter +link_finder_agent = OpenAIAgentAdapter( + role="Link Finder", + goal="Find the most relevant and high-quality resources for coding tasks.", + backstory="You are a research specialist with a talent for finding the most helpful resources. You're skilled at using search tools to discover documentation, tutorials, and examples that directly address the user's coding needs.", + tools=[SerperDevTool()], + allow_delegation=False, + verbose=True, +) + +# LangGraph Agent Adapter +reporter_agent = LangGraphAgentAdapter( + role="Reporter", + goal="Report the results of the tasks.", + backstory="You are a reporter who reports the results of the other tasks", + llm=ChatOpenAI(model="gpt-4o"), + allow_delegation=True, + verbose=True, +) + + +class Code(BaseModel): + code: str + + +task = Task( + description="Give an answer to the coding question: {task}", + expected_output="A thorough answer to the coding question: {task}", + agent=code_helper_agent, + output_json=Code, +) +task2 = Task( + description="Find links to resources that can help with coding tasks. Use the serper tool to find resources that can help.", + expected_output="A list of links to resources that can help with coding tasks", + agent=link_finder_agent, +) + + +class Report(BaseModel): + code: str + links: List[str] + + +task3 = Task( + description="Report the results of the tasks.", + expected_output="A report of the results of the tasks. this is the code produced and then the links to the resources that can help with the coding task.", + agent=reporter_agent, + output_json=Report, +) +# Usando no CrewAI +crew = Crew( + agents=[code_helper_agent, link_finder_agent, reporter_agent], + tasks=[task, task2, task3], + verbose=True, +) + +result = crew.kickoff( + inputs={"task": "How do you implement an abstract class in python?"} +) + +# Imprima o resultado bruto primeiro +print("Raw result:", result) + +# Lide com o resultado de acordo com seu tipo +if hasattr(result, "json_dict") and result.json_dict: + json_result = result.json_dict + print("\nStructured JSON result:") + print(f"{json.dumps(json_result, indent=2)}") + + # Acesse os campos de forma segura + if isinstance(json_result, dict): + if "code" in json_result: + print("\nCode:") + print( + json_result["code"][:200] + "..." + if len(json_result["code"]) > 200 + else json_result["code"] + ) + + if "links" in json_result: + print("\nLinks:") + for link in json_result["links"][:5]: # Print first 5 links + print(f"- {link}") + if len(json_result["links"]) > 5: + print(f"...and {len(json_result['links']) - 5} more links") +elif hasattr(result, "pydantic") and result.pydantic: + print("\nPydantic model result:") + print(result.pydantic.model_dump_json(indent=2)) +else: + # Fallback para saída bruta + print("\nNo structured result available, using raw output:") + print(result.raw[:500] + "..." if len(result.raw) > 500 else result.raw) + +``` \ No newline at end of file diff --git a/docs/pt-BR/learn/coding-agents.mdx b/docs/pt-BR/learn/coding-agents.mdx new file mode 100644 index 000000000..ccf17d8ca --- /dev/null +++ b/docs/pt-BR/learn/coding-agents.mdx @@ -0,0 +1,95 @@ +--- +title: Agentes de Codificação +description: Aprenda como habilitar seus Agentes CrewAI para escrever e executar código, e explore funcionalidades avançadas para maior potencial. +icon: rectangle-code +--- + +## Introdução + +Os Agentes CrewAI agora têm a poderosa capacidade de escrever e executar código, aumentando significativamente suas habilidades de resolução de problemas. Esse recurso é particularmente útil para tarefas que exigem soluções computacionais ou programáticas. + +## Habilitando a Execução de Código + +Para habilitar a execução de código para um agente, defina o parâmetro `allow_code_execution` como `True` ao criar o agente. + +Veja um exemplo: + +```python Code +from crewai import Agent + +coding_agent = Agent( + role="Senior Python Developer", + goal="Craft well-designed and thought-out code", + backstory="You are a senior Python developer with extensive experience in software architecture and best practices.", + allow_code_execution=True +) +``` + + +Observe que o parâmetro `allow_code_execution` é `False` por padrão. + + +## Considerações Importantes + +1. **Seleção de Modelo**: É fortemente recomendado utilizar modelos mais avançados como Claude 3.5 Sonnet e GPT-4 ao habilitar a execução de código. +Esses modelos têm melhor compreensão de conceitos de programação e tendem a gerar códigos mais corretos e eficientes. + +2. **Tratamento de Erros**: O recurso de execução de código inclui tratamento de erros. Se o código executado gerar uma exceção, o agente receberá a mensagem de erro e poderá tentar corrigir o código ou +fornecer soluções alternativas. O parâmetro `max_retry_limit`, que por padrão é 2, controla o número máximo de tentativas para uma tarefa. + +3. **Dependências**: Para usar o recurso de execução de código, é necessário instalar o pacote `crewai_tools`. Caso não esteja instalado, o agente registrará uma mensagem informativa: +"Ferramentas de codificação não disponíveis. Instale crewai_tools." + +## Processo de Execução de Código + +Quando um agente com execução de código habilitada encontra uma tarefa que requer programação: + + + + O agente analisa a tarefa e determina que a execução de código é necessária. + + + Ele formula o código Python necessário para resolver o problema. + + + O código é enviado para a ferramenta interna de execução de código (`CodeInterpreterTool`). + + + O agente interpreta o resultado e o incorpora na sua resposta ou o utiliza para aprofundar a solução do problema. + + + +## Exemplo de Uso + +Veja um exemplo detalhado de como criar um agente com capacidade de execução de código e utilizá-lo em uma tarefa: + +```python Code +from crewai import Agent, Task, Crew + +# Create an agent with code execution enabled +coding_agent = Agent( + role="Python Data Analyst", + goal="Analyze data and provide insights using Python", + backstory="You are an experienced data analyst with strong Python skills.", + allow_code_execution=True +) + +# Create a task that requires code execution +data_analysis_task = Task( + description="Analyze the given dataset and calculate the average age of participants.", + agent=coding_agent +) + +# Create a crew and add the task +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +# Execute the crew +result = analysis_crew.kickoff() + +print(result) +``` + +Neste exemplo, o `coding_agent` pode escrever e executar código Python para realizar tarefas de análise de dados. \ No newline at end of file diff --git a/docs/pt-BR/learn/conditional-tasks.mdx b/docs/pt-BR/learn/conditional-tasks.mdx new file mode 100644 index 000000000..3a4490ab4 --- /dev/null +++ b/docs/pt-BR/learn/conditional-tasks.mdx @@ -0,0 +1,89 @@ +--- +title: Tarefas Condicionais +description: Saiba como usar tarefas condicionais em um kickoff do crewAI +icon: diagram-subtask +--- + +## Introdução + +As Tarefas Condicionais no crewAI permitem a adaptação dinâmica do fluxo de trabalho com base nos resultados de tarefas anteriores. +Esse recurso poderoso possibilita que crews tomem decisões e executem tarefas seletivamente, aumentando a flexibilidade e a eficiência dos seus processos orientados por IA. + +## Exemplo de Uso + +```python Code +from typing import List +from pydantic import BaseModel +from crewai import Agent, Crew +from crewai.tasks.conditional_task import ConditionalTask +from crewai.tasks.task_output import TaskOutput +from crewai.task import Task +from crewai_tools import SerperDevTool + +# Define a condition function for the conditional task +# If false, the task will be skipped, if true, then execute the task. +def is_data_missing(output: TaskOutput) -> bool: + return len(output.pydantic.events) < 10 # this will skip this task + +# Define the agents +data_fetcher_agent = Agent( + role="Data Fetcher", + goal="Fetch data online using Serper tool", + backstory="Backstory 1", + verbose=True, + tools=[SerperDevTool()] +) + +data_processor_agent = Agent( + role="Data Processor", + goal="Process fetched data", + backstory="Backstory 2", + verbose=True +) + +summary_generator_agent = Agent( + role="Summary Generator", + goal="Generate summary from fetched data", + backstory="Backstory 3", + verbose=True +) + +class EventOutput(BaseModel): + events: List[str] + +task1 = Task( + description="Fetch data about events in San Francisco using Serper tool", + expected_output="List of 10 things to do in SF this week", + agent=data_fetcher_agent, + output_pydantic=EventOutput, +) + +conditional_task = ConditionalTask( + description=""" + Check if data is missing. If we have less than 10 events, + fetch more events using Serper tool so that + we have a total of 10 events in SF this week.. + """, + expected_output="List of 10 Things to do in SF this week", + condition=is_data_missing, + agent=data_processor_agent, +) + +task3 = Task( + description="Generate summary of events in San Francisco from fetched data", + expected_output="A complete report on the customer and their customers and competitors, including their demographics, preferences, market positioning and audience engagement.", + agent=summary_generator_agent, +) + +# Create a crew with the tasks +crew = Crew( + agents=[data_fetcher_agent, data_processor_agent, summary_generator_agent], + tasks=[task1, conditional_task, task3], + verbose=True, + planning=True +) + +# Run the crew +result = crew.kickoff() +print("results", result) +``` \ No newline at end of file diff --git a/docs/pt-BR/learn/create-custom-tools.mdx b/docs/pt-BR/learn/create-custom-tools.mdx new file mode 100644 index 000000000..26360f95c --- /dev/null +++ b/docs/pt-BR/learn/create-custom-tools.mdx @@ -0,0 +1,69 @@ +--- +title: Criar Ferramentas Personalizadas +description: Guia abrangente sobre como criar, utilizar e gerenciar ferramentas personalizadas dentro do framework CrewAI, incluindo novas funcionalidades e tratamento de erros. +icon: hammer +--- + +## Criando e Utilizando Ferramentas no CrewAI + +Este guia traz instruções detalhadas sobre como criar ferramentas personalizadas para o framework CrewAI e como gerenciar e utilizar essas ferramentas de forma eficiente, +incorporando funcionalidades recentes, como delegação de ferramentas, tratamento de erros e chamada dinâmica de ferramentas. Destaca também a importância de ferramentas de colaboração, +permitindo que agentes executem uma ampla gama de ações. + +### Subclassificando `BaseTool` + +Para criar uma ferramenta personalizada, herde de `BaseTool` e defina os atributos necessários, incluindo o `args_schema` para validação de entrada e o método `_run`. + +```python Code +from typing import Type +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + +class MyToolInput(BaseModel): + """Input schema for MyCustomTool.""" + argument: str = Field(..., description="Description of the argument.") + +class MyCustomTool(BaseTool): + name: str = "Name of my tool" + description: str = "What this tool does. It's vital for effective utilization." + args_schema: Type[BaseModel] = MyToolInput + + def _run(self, argument: str) -> str: + # Your tool's logic here + return "Tool's result" +``` + +### Usando o Decorador `tool` + +Como alternativa, você pode utilizar o decorador de ferramenta `@tool`. Esta abordagem permite definir os atributos e as funcionalidades da ferramenta diretamente em uma função, +oferecendo uma maneira concisa e eficiente de criar ferramentas especializadas de acordo com suas necessidades. + +```python Code +from crewai.tools import tool + +@tool("Tool Name") +def my_simple_tool(question: str) -> str: + """Tool description for clarity.""" + # Tool logic here + return "Tool output" +``` + +### Definindo uma Função de Cache para a Ferramenta + +Para otimizar o desempenho da ferramenta com cache, defina estratégias de cache personalizadas utilizando o atributo `cache_function`. + +```python Code +@tool("Tool with Caching") +def cached_tool(argument: str) -> str: + """Tool functionality description.""" + return "Cacheable result" + +def my_cache_strategy(arguments: dict, result: str) -> bool: + # Define custom caching logic + return True if some_condition else False + +cached_tool.cache_function = my_cache_strategy +``` + +Seguindo essas orientações e incorporando novas funcionalidades e ferramentas de colaboração nos seus processos de criação e gerenciamento de ferramentas, +você pode aproveitar ao máximo as capacidades do framework CrewAI, aprimorando tanto a experiência de desenvolvimento quanto a eficiência dos seus agentes de IA. \ No newline at end of file diff --git a/docs/pt-BR/learn/custom-llm.mdx b/docs/pt-BR/learn/custom-llm.mdx new file mode 100644 index 000000000..f0e75d034 --- /dev/null +++ b/docs/pt-BR/learn/custom-llm.mdx @@ -0,0 +1,122 @@ +--- +title: Implementação de LLM Personalizada +description: Aprenda a criar implementações personalizadas de LLM no CrewAI. +icon: code +--- + +## Visão Geral + +O CrewAI oferece suporte a implementações personalizadas de LLM por meio da classe abstrata `BaseLLM`. Isso permite integrar qualquer provedor de LLM que não tenha suporte nativo no LiteLLM ou implementar mecanismos de autenticação personalizados. + +## Início Rápido + +Aqui está uma implementação mínima de LLM personalizada: + +```python +# (não traduzir blocos de código) +``` + +## Usando Seu LLM Personalizado + +```python +# (não traduzir blocos de código) +``` + +## Métodos Necessários + +### Construtor: `__init__()` + +**Crítico**: Você deve chamar `super().__init__(model, temperature)` com os parâmetros necessários: + +```python +# (não traduzir blocos de código) +``` + +### Método Abstrato: `call()` + +O método `call()` é o núcleo da sua implementação de LLM. Ele deve: + +- Aceitar mensagens (string ou lista de dicionários com 'role' e 'content') +- Retornar uma resposta como string +- Lidar com ferramentas e chamada de funções, se suportado +- Lançar exceções apropriadas para erros + +### Métodos Opcionais + +```python +# (não traduzir blocos de código) +``` + +## Padrões Comuns + +### Tratamento de Erros + +```python +# (não traduzir blocos de código) +``` + +### Autenticação Personalizada + +```python +# (não traduzir blocos de código) +``` + +### Suporte a Stop Words + +O CrewAI adiciona automaticamente `"\nObservation:"` como stop word para controlar o comportamento do agente. Se o seu LLM suporta stop words: + +```python +# (não traduzir blocos de código) +``` + +Se o seu LLM não suporta stop words nativamente: + +```python +# (não traduzir blocos de código) +``` + +## Chamada de Funções + +Se o seu LLM suporta chamada de funções, implemente o fluxo completo: + +```python +# (não traduzir blocos de código) +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros no Construtor** +```python +# ❌ Errado - parâmetros obrigatórios ausentes +def __init__(self, api_key: str): + super().__init__() + +# ✅ Correto +def __init__(self, model: str, api_key: str, temperature: Optional[float] = None): + super().__init__(model=model, temperature=temperature) +``` + +**Chamada de Funções Não Funciona** +- Certifique-se de que `supports_function_calling()` retorna `True` +- Verifique se você lida com `tool_calls` na resposta +- Assegure-se de que o parâmetro `available_functions` está sendo corretamente utilizado + +**Falhas de Autenticação** +- Verifique o formato e as permissões da chave de API +- Confira o formato do header de autenticação +- Certifique-se de que as URLs dos endpoints estão corretas + +**Erros de Parsing de Resposta** +- Valide a estrutura da resposta antes de acessar campos aninhados +- Trate casos em que o content pode ser None +- Adicione tratamento de erros para respostas malformadas + +## Testando Seu LLM Personalizado + +```python +# (não traduzir blocos de código) +``` + +Este guia cobre o essencial para implementar LLMs personalizados no CrewAI. \ No newline at end of file diff --git a/docs/pt-BR/learn/custom-manager-agent.mdx b/docs/pt-BR/learn/custom-manager-agent.mdx new file mode 100644 index 000000000..ee7e1e4fd --- /dev/null +++ b/docs/pt-BR/learn/custom-manager-agent.mdx @@ -0,0 +1,90 @@ +--- +title: Agente Gerente Personalizado +description: Saiba como definir um agente personalizado como gerente no CrewAI, proporcionando mais controle sobre o gerenciamento e a coordenação das tarefas. +icon: user-shield +--- + +# Definindo um Agente Específico como Gerente no CrewAI + +O CrewAI permite que usuários definam um agente específico como gerente da crew, oferecendo mais controle sobre o gerenciamento e a coordenação das tarefas. +Esse recurso possibilita a personalização do papel gerencial para se adequar melhor às necessidades do seu projeto. + +## Utilizando o Atributo `manager_agent` + +### Agente Gerente Personalizado + +O atributo `manager_agent` permite que você defina um agente personalizado para gerenciar a crew. Este agente supervisionará todo o processo, garantindo que as tarefas sejam concluídas de forma eficiente e com o mais alto padrão de qualidade. + +### Exemplo + +```python Code +import os +from crewai import Agent, Task, Crew, Process + +# Define your agents +researcher = Agent( + role="Researcher", + goal="Conduct thorough research and analysis on AI and AI agents", + backstory="You're an expert researcher, specialized in technology, software engineering, AI, and startups. You work as a freelancer and are currently researching for a new client.", + allow_delegation=False, +) + +writer = Agent( + role="Senior Writer", + goal="Create compelling content about AI and AI agents", + backstory="You're a senior writer, specialized in technology, software engineering, AI, and startups. You work as a freelancer and are currently writing content for a new client.", + allow_delegation=False, +) + +# Define your task +task = Task( + description="Generate a list of 5 interesting ideas for an article, then write one captivating paragraph for each idea that showcases the potential of a full article on this topic. Return the list of ideas with their paragraphs and your notes.", + expected_output="5 bullet points, each with a paragraph and accompanying notes.", +) + +# Define the manager agent +manager = Agent( + role="Project Manager", + goal="Efficiently manage the crew and ensure high-quality task completion", + backstory="You're an experienced project manager, skilled in overseeing complex projects and guiding teams to success. Your role is to coordinate the efforts of the crew members, ensuring that each task is completed on time and to the highest standard.", + allow_delegation=True, +) + +# Instantiate your crew with a custom manager +crew = Crew( + agents=[researcher, writer], + tasks=[task], + manager_agent=manager, + process=Process.hierarchical, +) + +# Start the crew's work +result = crew.kickoff() +``` + +## Benefícios de um Agente Gerente Personalizado + +- **Controle aprimorado**: Adapte a abordagem de gerenciamento para atender às necessidades específicas do seu projeto. +- **Coordenação melhorada**: Assegure uma coordenação e gestão eficiente das tarefas por um agente experiente. +- **Gestão personalizável**: Defina funções e responsabilidades gerenciais que estejam alinhadas aos objetivos do seu projeto. + +## Definindo um Manager LLM + +Se você estiver utilizando o processo hierarchical e não quiser definir um agente gerente personalizado, é possível especificar o modelo de linguagem para o gerente: + +```python Code +from crewai import LLM + +manager_llm = LLM(model="gpt-4o") + +crew = Crew( + agents=[researcher, writer], + tasks=[task], + process=Process.hierarchical, + manager_llm=manager_llm +) +``` + + +É necessário definir `manager_agent` ou `manager_llm` ao utilizar o processo hierarchical. + \ No newline at end of file diff --git a/docs/pt-BR/learn/customizing-agents.mdx b/docs/pt-BR/learn/customizing-agents.mdx new file mode 100644 index 000000000..27c411a97 --- /dev/null +++ b/docs/pt-BR/learn/customizing-agents.mdx @@ -0,0 +1,111 @@ +--- +title: Personalize Agentes +description: Um guia abrangente para adaptar agentes a funções específicas, tarefas e customizações avançadas dentro do framework CrewAI. +icon: user-pen +--- + +## Atributos Personalizáveis + +A construção de uma equipe CrewAI eficiente depende da capacidade de adaptar dinamicamente seus agentes de IA para atender aos requisitos únicos de qualquer projeto. Esta seção aborda os atributos fundamentais que você pode personalizar. + +### Principais Atributos para Personalização + +| Atributo | Descrição | +|:------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Role** | Especifica a função do agente dentro da equipe, como 'Analista' ou 'Representante de Atendimento ao Cliente'. | +| **Goal** | Define os objetivos do agente, alinhados à sua função e à missão geral da equipe. | +| **Backstory** | Fornece profundidade à persona do agente, aprimorando motivações e engajamento dentro da equipe. | +| **Tools** *(Opcional)* | Representa as capacidades ou métodos que o agente utiliza para tarefas, desde funções simples até integrações complexas. | +| **Cache** *(Opcional)* | Determina se o agente deve usar cache para o uso de ferramentas. | +| **Max RPM** | Define o número máximo de requisições por minuto (`max_rpm`). Pode ser definido como `None` para requisições ilimitadas a serviços externos. | +| **Verbose** *(Opcional)* | Ativa registros detalhados para depuração e otimização, fornecendo insights sobre os processos de execução. | +| **Allow Delegation** *(Opcional)* | Controla a delegação de tarefas para outros agentes, padrão é `False`. | +| **Max Iter** *(Opcional)* | Limita o número máximo de iterações (`max_iter`) para uma tarefa, prevenindo loops infinitos, com valor padrão de 25. | +| **Max Execution Time** *(Opcional)* | Define o tempo máximo permitido para que o agente complete uma tarefa. | +| **System Template** *(Opcional)* | Define o formato do sistema para o agente. | +| **Prompt Template** *(Opcional)* | Define o formato do prompt para o agente. | +| **Response Template** *(Opcional)* | Define o formato da resposta para o agente. | +| **Use System Prompt** *(Opcional)* | Controla se o agente irá usar um prompt de sistema durante a execução de tarefas. | +| **Respect Context Window** | Ativa uma janela deslizante de contexto por padrão, mantendo o tamanho do contexto. | +| **Max Retry Limit** | Define o número máximo de tentativas (`max_retry_limit`) para um agente em caso de erros. | + +## Opções Avançadas de Personalização + +Além dos atributos básicos, o CrewAI permite customizações mais profundas para aprimorar significativamente o comportamento e as capacidades de um agente. + +### Personalização de Modelo de Linguagem + +Agentes podem ser personalizados com modelos de linguagem específicos (`llm`) e modelos de linguagem com chamada de função (`function_calling_llm`), oferecendo controle avançado sobre o processamento e a tomada de decisão. +É importante notar que definir o `function_calling_llm` permite sobrescrever o modelo padrão de chamada de função da equipe, proporcionando maior grau de personalização. + +## Ajustes de Performance e Depuração + +Ajustar a performance do agente e monitorar suas operações é fundamental para a execução eficiente de tarefas. + +### Modo Verbose e Limite de RPM + +- **Modo Verbose**: Ativa o registro detalhado das ações do agente, útil para depuração e otimização. Especificamente, fornece insights sobre os processos de execução do agente, auxiliando na otimização de performance. +- **Limite de RPM**: Define o número máximo de requisições por minuto (`max_rpm`). Este atributo é opcional e pode ser definido como `None` para não haver limite, permitindo consultas ilimitadas a serviços externos, se necessário. + +### Máximo de Iterações por Execução de Tarefa + +O atributo `max_iter` permite ao usuário definir o número máximo de iterações que um agente pode executar para uma única tarefa, prevenindo loops infinitos ou execuções excessivamente longas. +O valor padrão é 25, fornecendo um equilíbrio entre profundidade e eficiência. Quando o agente chega próximo a esse número, ele tentará entregar a melhor resposta possível. + +## Personalizando Agentes e Ferramentas + +Agentes são personalizados definindo seus atributos e ferramentas durante a inicialização. As ferramentas são críticas para a funcionalidade do agente, permitindo que realizem tarefas especializadas. +O atributo `tools` deve ser um array de ferramentas que o agente pode utilizar, e, por padrão, é inicializado como uma lista vazia. As ferramentas podem ser adicionadas ou modificadas após a criação do agente para se adaptar a novos requisitos. + +```shell +pip install 'crewai[tools]' +``` + +### Exemplo: Atribuindo Ferramentas a um Agente + +```python Code +import os +from crewai import Agent +from crewai_tools import SerperDevTool + +# Defina as chaves de API para inicialização da ferramenta +os.environ["OPENAI_API_KEY"] = "Sua Chave" +os.environ["SERPER_API_KEY"] = "Sua Chave" + +# Inicialize uma ferramenta de busca +search_tool = SerperDevTool() + +# Inicialize o agente com opções avançadas +agent = Agent( + role='Research Analyst', + goal='Provide up-to-date market analysis', + backstory='An expert analyst with a keen eye for market trends.', + tools=[search_tool], + memory=True, # Ativa memória + verbose=True, + max_rpm=None, # Sem limite de requisições por minuto + max_iter=25, # Valor padrão de máximo de iterações +) +``` + +## Delegação e Autonomia + +Controlar a capacidade de um agente delegar tarefas ou fazer perguntas é fundamental para ajustar sua autonomia e a dinâmica de colaboração dentro do framework CrewAI. Por padrão, +o atributo `allow_delegation` agora é definido como `False`, desabilitando para que agentes busquem assistência ou deleguem tarefas conforme necessário. Esse comportamento padrão pode ser alterado para promover resolução colaborativa de problemas e +eficiência dentro do ecossistema CrewAI. Se necessário, a delegação pode ser ativada para atender requisitos operacionais específicos. + +### Exemplo: Desabilitando Delegação para um Agente + +```python Code +agent = Agent( + role='Content Writer', + goal='Write engaging content on market trends', + backstory='A seasoned writer with expertise in market analysis.', + allow_delegation=True # Habilitando delegação +) +``` + +## Conclusão + +Personalizar agentes no CrewAI definindo seus papéis, objetivos, histórias e ferramentas, juntamente com opções avançadas como personalização de modelo de linguagem, memória, ajustes de performance e preferências de delegação, +proporciona uma equipe de IA sofisticada e preparada para enfrentar desafios complexos. \ No newline at end of file diff --git a/docs/pt-BR/learn/dalle-image-generation.mdx b/docs/pt-BR/learn/dalle-image-generation.mdx new file mode 100644 index 000000000..8c54a0081 --- /dev/null +++ b/docs/pt-BR/learn/dalle-image-generation.mdx @@ -0,0 +1,73 @@ +--- +title: "Geração de Imagens com DALL-E" +description: "Aprenda a usar o DALL-E para geração de imagens com IA em seus projetos CrewAI" +icon: "image" +--- + +O CrewAI oferece integração com o DALL-E da OpenAI, permitindo que seus agentes de IA gerem imagens como parte de suas tarefas. Este guia irá orientá-lo sobre como configurar e utilizar a ferramenta DALL-E em seus projetos CrewAI. + +## Pré-requisitos + +- crewAI instalado (última versão) +- Chave de API OpenAI com acesso ao DALL-E + +## Configurando a Ferramenta DALL-E + + + + ```python + from crewai_tools import DallETool + ``` + + + + ```python + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], + tools=[SerperDevTool(), DallETool()], # Add DallETool to the list of tools + allow_delegation=False, + verbose=True + ) + ``` + + + +## Utilizando a Ferramenta DALL-E + +Depois de adicionar a ferramenta DALL-E ao seu agente, ele poderá gerar imagens baseadas em prompts de texto. A ferramenta retornará uma URL para a imagem gerada, que pode ser utilizada na resposta do agente ou repassada para outros agentes para processamento adicional. + +### Exemplo de Configuração de Agente + +```yaml +role: > + Pesquisador Sênior de Dados para Perfis do LinkedIn +goal: > + Encontrar perfis detalhados do LinkedIn com base no nome fornecido {name} e domínio {domain} + Gerar uma imagem com o Dall-e baseada no domínio {domain} +backstory: > + Você é um pesquisador experiente com habilidade para encontrar os perfis do LinkedIn mais relevantes. + Conhecido por sua eficiência em navegar no LinkedIn, você se destaca em reunir e apresentar + informações profissionais de forma clara e concisa. +``` + +### Resultado Esperado + +O agente com a ferramenta DALL-E conseguirá gerar a imagem e fornecer uma URL em sua resposta. Você poderá então baixar a imagem. + + + Imagem DALL-E + + +## Boas Práticas + +1. **Seja específico nos prompts de geração de imagem** para obter melhores resultados. +2. **Considere o tempo de geração** - A geração de imagens pode levar algum tempo, então inclua isso no seu planejamento de tarefas. +3. **Siga as políticas de uso** - Sempre cumpra as políticas de uso da OpenAI ao gerar imagens. + +## Solução de Problemas + +1. **Verifique o acesso à API** - Certifique-se de que sua chave de API OpenAI possui acesso ao DALL-E. +2. **Compatibilidade de versões** - Verifique se você está utilizando a versão mais recente do crewAI e crewai-tools. +3. **Configuração da ferramenta** - Confirme que a ferramenta DALL-E foi corretamente adicionada à lista de ferramentas do agente. \ No newline at end of file diff --git a/docs/pt-BR/learn/force-tool-output-as-result.mdx b/docs/pt-BR/learn/force-tool-output-as-result.mdx new file mode 100644 index 000000000..56d236381 --- /dev/null +++ b/docs/pt-BR/learn/force-tool-output-as-result.mdx @@ -0,0 +1,50 @@ +--- +title: Forçar a Saída da Ferramenta como Resultado +description: Aprenda como forçar a saída de uma ferramenta como resultado em uma tarefa de Agent no CrewAI. +icon: wrench-simple +--- + +## Introdução + +No CrewAI, você pode forçar a saída de uma ferramenta como o resultado de uma tarefa de um agent. +Esse recurso é útil quando você deseja garantir que a saída da ferramenta seja capturada e retornada como resultado da tarefa, evitando quaisquer modificações pelo agent durante a execução da tarefa. + +## Forçando a Saída da Ferramenta como Resultado + +Para forçar a saída da ferramenta como resultado da tarefa de um agent, você precisa definir o parâmetro `result_as_answer` como `True` ao adicionar uma ferramenta ao agent. +Esse parâmetro garante que a saída da ferramenta seja capturada e retornada como resultado da tarefa, sem qualquer modificação pelo agent. + +Veja um exemplo de como forçar a saída da ferramenta como resultado da tarefa de um agent: + +```python Code +from crewai.agent import Agent +from my_tool import MyCustomTool + +# Create a coding agent with the custom tool +coding_agent = Agent( + role="Data Scientist", + goal="Produce amazing reports on AI", + backstory="You work with data and AI", + tools=[MyCustomTool(result_as_answer=True)], + ) + +# Assuming the tool's execution and result population occurs within the system +task_result = coding_agent.execute_task(task) +``` + +## Fluxo de Trabalho em Ação + + + + O agent executa a tarefa utilizando a ferramenta fornecida. + + + A ferramenta gera a saída, que é capturada como resultado da tarefa. + + + O agent pode refletir e aprender com a ferramenta, mas a saída não é modificada. + + + A saída da ferramenta é retornada como resultado da tarefa sem quaisquer modificações. + + \ No newline at end of file diff --git a/docs/pt-BR/learn/hierarchical-process.mdx b/docs/pt-BR/learn/hierarchical-process.mdx new file mode 100644 index 000000000..c82c319ed --- /dev/null +++ b/docs/pt-BR/learn/hierarchical-process.mdx @@ -0,0 +1,111 @@ +--- +title: Processo Hierárquico +description: Um guia abrangente para compreender e aplicar o processo hierárquico em seus projetos CrewAI, atualizado para refletir as práticas de codificação e funcionalidades mais recentes. +icon: sitemap +--- + +## Introdução + +O processo hierárquico no CrewAI introduz uma abordagem estruturada para a gestão de tarefas, simulando hierarquias organizacionais tradicionais para uma delegação e execução eficiente de tarefas. +Esse fluxo de trabalho sistemático melhora os resultados do projeto ao garantir que as tarefas sejam tratadas com máxima eficiência e precisão. + + + O processo hierárquico foi projetado para alavancar modelos avançados como o GPT-4, otimizando o uso de tokens enquanto lida com tarefas complexas de forma mais eficiente. + + +## Visão Geral do Processo Hierárquico + +Por padrão, as tarefas no CrewAI são gerenciadas por meio de um processo sequencial. No entanto, adotar uma abordagem hierárquica permite uma hierarquia clara na gestão de tarefas, +onde um agente 'gerente' coordena o fluxo de trabalho, delega tarefas e valida os resultados para uma execução eficaz e simplificada. Esse agente gerente pode agora ser +criado automaticamente pelo CrewAI ou explicitamente definido pelo usuário. + +### Principais Características + +- **Delegação de Tarefas**: Um agente gerente distribui tarefas entre os membros da crew com base em seus papéis e capacidades. +- **Validação de Resultados**: O gerente avalia os resultados para garantir que atendam aos padrões exigidos. +- **Fluxo de Trabalho Eficiente**: Emula estruturas corporativas, oferecendo uma abordagem organizada para a gestão de tarefas. +- **Manipulação de System Prompt**: Opcionalmente, especifique se o sistema deve usar prompts predefinidos. +- **Controle de Stop Words**: Opcionalmente, especifique se stop words devem ser usadas, oferecendo suporte a diversos modelos, incluindo os modelos o1. +- **Respeito à Context Window**: Priorização de contexto relevante ativando o respeito à context window, que agora é o comportamento padrão. +- **Controle de Delegação**: A delegação agora está desativada por padrão para dar controle explícito ao usuário. +- **Máximo de Requisições por Minuto**: Opção configurável para definir o número máximo de requisições por minuto. +- **Máximo de Iterações**: Limitação do número máximo de iterações até a obtenção de uma resposta final. + +## Implementando o Processo Hierárquico + +Para utilizar o processo hierárquico, é essencial definir explicitamente o atributo de processo como `Process.hierarchical`, já que o comportamento padrão é `Process.sequential`. +Defina uma crew com um gerente designado e estabeleça uma cadeia de comando clara. + + + Atribua ferramentas no nível do agente para facilitar a delegação e execução de tarefas pelos agentes designados sob a orientação do gerente. + Ferramentas também podem ser especificadas no nível da tarefa, para um controle preciso sobre a disponibilidade de ferramentas durante a execução das tarefas. + + + + Configurar o parâmetro `manager_llm` é fundamental para o processo hierárquico. + O sistema exige a configuração de um LLM do gerente para funcionar corretamente, garantindo tomadas de decisão personalizadas. + + +```python Code +from crewai import Crew, Process, Agent + +# Agents are defined with attributes for backstory, cache, and verbose mode +researcher = Agent( + role='Researcher', + goal='Conduct in-depth analysis', + backstory='Experienced data analyst with a knack for uncovering hidden trends.', +) +writer = Agent( + role='Writer', + goal='Create engaging content', + backstory='Creative writer passionate about storytelling in technical domains.', +) + +# Establishing the crew with a hierarchical process and additional configurations +project_crew = Crew( + tasks=[...], # Tasks to be delegated and executed under the manager's supervision + agents=[researcher, writer], + manager_llm="gpt-4o", # Specify which LLM the manager should use + process=Process.hierarchical, + planning=True, +) +``` + +### Usando um Agente Gerente Personalizado + +Alternativamente, você pode criar um agente gerente personalizado com atributos específicos adaptados às necessidades de gestão do seu projeto. Isso oferece maior controle sobre o comportamento e as capacidades do gerente. + +```python +# Define a custom manager agent +manager = Agent( + role="Project Manager", + goal="Efficiently manage the crew and ensure high-quality task completion", + backstory="You're an experienced project manager, skilled in overseeing complex projects and guiding teams to success.", + allow_delegation=True, +) + +# Use the custom manager in your crew +project_crew = Crew( + tasks=[...], + agents=[researcher, writer], + manager_agent=manager, # Use your custom manager agent + process=Process.hierarchical, + planning=True, +) +``` + + + Para mais detalhes sobre a criação e personalização de um agente gerente, confira a [documentação do Custom Manager Agent](https://docs.crewai.com/how-to/custom-manager-agent#custom-manager-agent). + + + +### Fluxo de Trabalho na Prática + +1. **Atribuição de Tarefas**: O gerente atribui as tarefas estrategicamente, considerando as capacidades de cada agente e as ferramentas disponíveis. +2. **Execução e Revisão**: Os agentes concluem suas tarefas com a opção de execução assíncrona e funções de callback para fluxos de trabalho otimizados. +3. **Progresso Sequencial das Tarefas**: Apesar de ser um processo hierárquico, as tarefas seguem uma ordem lógica para um progresso fluido, facilitado pela supervisão do gerente. + +## Conclusão + +Adotar o processo hierárquico no CrewAI, com as configurações corretas e o entendimento das capacidades do sistema, facilita uma abordagem organizada e eficiente para o gerenciamento de projetos. +Aproveite os recursos avançados e as personalizações para ajustar o fluxo de trabalho conforme suas necessidades, garantindo a execução ideal das tarefas e o sucesso do projeto. \ No newline at end of file diff --git a/docs/pt-BR/learn/human-in-the-loop.mdx b/docs/pt-BR/learn/human-in-the-loop.mdx new file mode 100644 index 000000000..7c7121233 --- /dev/null +++ b/docs/pt-BR/learn/human-in-the-loop.mdx @@ -0,0 +1,78 @@ +--- +title: "Workflows Human-in-the-Loop (HITL)" +description: "Aprenda como implementar workflows Human-in-the-Loop na CrewAI para aprimorar a tomada de decisões" +icon: "user-check" +--- + +Human-in-the-Loop (HITL) é uma abordagem poderosa que combina a inteligência artificial com a experiência humana para aprimorar a tomada de decisões e melhorar os resultados das tarefas. Este guia mostra como implementar HITL dentro da CrewAI. + +## Configurando Workflows HITL + + + + Configure sua tarefa com a entrada humana habilitada: + + Entrada Humana Crew + + + + + Ao iniciar seu crew, inclua uma URL de webhook para entrada humana: + + URL do Webhook Crew + + + + + Assim que o crew concluir a tarefa que requer entrada humana, você receberá uma notificação de webhook contendo: + - Execution ID + - Task ID + - Task output + + + + O sistema irá pausar no estado `Pending Human Input`. Revise cuidadosamente o resultado da tarefa. + + + + Chame o endpoint de retomada do seu crew com as seguintes informações: + + Endpoint de Retomada Crew + + + **Impacto do Feedback na Execução da Tarefa**: + É fundamental ter cuidado ao fornecer feedback, pois todo o conteúdo do feedback será incorporado como contexto adicional para execuções futuras da tarefa. + + Isso significa: + - Todas as informações do seu feedback passam a fazer parte do contexto da tarefa. + - Detalhes irrelevantes podem influenciar negativamente. + - Feedback conciso e relevante ajuda a manter o foco e a eficiência da tarefa. + - Sempre revise seu feedback cuidadosamente antes de enviar para garantir que contenha apenas informações pertinentes que irão guiar positivamente a execução da tarefa. + + + Se você fornecer um feedback negativo: + - O crew irá tentar novamente a tarefa com o contexto adicionado do seu feedback. + - Você receberá outra notificação de webhook para nova revisão. + - Repita os passos 4-6 até ficar satisfeito. + + + + Quando você enviar um feedback positivo, a execução prosseguirá para as próximas etapas. + + + +## Melhores Práticas + +- **Seja Específico**: Forneça feedback claro e acionável que trate diretamente da tarefa em questão +- **Mantenha-se Relevante**: Inclua apenas informações que ajudem a melhorar a execução da tarefa +- **Seja Ágil**: Responda rapidamente às solicitações HITL para evitar atrasos no fluxo +- **Reveja Cuidadosamente**: Verifique seu feedback antes de enviar para garantir a precisão + +## Casos de Uso Comuns + +Workflows HITL são particularmente valiosos para: +- Garantia de qualidade e validação +- Cenários de tomada de decisão complexa +- Operações sensíveis ou de alto risco +- Tarefas criativas que requerem julgamento humano +- Revisões de conformidade e regulamentação \ No newline at end of file diff --git a/docs/pt-BR/learn/human-input-on-execution.mdx b/docs/pt-BR/learn/human-input-on-execution.mdx new file mode 100644 index 000000000..e7c8732d3 --- /dev/null +++ b/docs/pt-BR/learn/human-input-on-execution.mdx @@ -0,0 +1,98 @@ +--- +title: Input Humano na Execução +description: Integrando o CrewAI com input humano durante a execução em processos complexos de tomada de decisão e aproveitando ao máximo todos os atributos e ferramentas do agente. +icon: user-check +--- + +## Input humano na execução dos agentes + +O input humano é fundamental em vários cenários de execução de agentes, permitindo que os agentes solicitem informações adicionais ou esclarecimentos quando necessário. +Esse recurso é especialmente útil em processos complexos de tomada de decisão ou quando os agentes precisam de mais detalhes para concluir uma tarefa de forma eficaz. + +## Usando input humano com CrewAI + +Para integrar input humano durante a execução do agente, defina o parâmetro `human_input` na definição da tarefa. Quando ativado, o agente solicitará informações ao usuário antes de fornecer sua resposta final. +Esse input pode oferecer contexto extra, esclarecer ambiguidades ou validar a saída produzida pelo agente. + +### Exemplo: + +```shell +pip install crewai +``` + +```python Code +import os +from crewai import Agent, Task, Crew +from crewai_tools import SerperDevTool + +os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key +os.environ["OPENAI_API_KEY"] = "Your Key" + +# Loading Tools +search_tool = SerperDevTool() + +# Define your agents with roles, goals, tools, and additional attributes +researcher = Agent( + role='Senior Research Analyst', + goal='Uncover cutting-edge developments in AI and data science', + backstory=( + "You are a Senior Research Analyst at a leading tech think tank. " + "Your expertise lies in identifying emerging trends and technologies in AI and data science. " + "You have a knack for dissecting complex data and presenting actionable insights." + ), + verbose=True, + allow_delegation=False, + tools=[search_tool] +) +writer = Agent( + role='Tech Content Strategist', + goal='Craft compelling content on tech advancements', + backstory=( + "You are a renowned Tech Content Strategist, known for your insightful and engaging articles on technology and innovation. " + "With a deep understanding of the tech industry, you transform complex concepts into compelling narratives." + ), + verbose=True, + allow_delegation=True, + tools=[search_tool], + cache=False, # Disable cache for this agent +) + +# Create tasks for your agents +task1 = Task( + description=( + "Conduct a comprehensive analysis of the latest advancements in AI in 2025. " + "Identify key trends, breakthrough technologies, and potential industry impacts. " + "Compile your findings in a detailed report. " + "Make sure to check with a human if the draft is good before finalizing your answer." + ), + expected_output='A comprehensive full report on the latest AI advancements in 2025, leave nothing out', + agent=researcher, + human_input=True +) + +task2 = Task( + description=( + "Using the insights from the researcher\'s report, develop an engaging blog post that highlights the most significant AI advancements. " + "Your post should be informative yet accessible, catering to a tech-savvy audience. " + "Aim for a narrative that captures the essence of these breakthroughs and their implications for the future." + ), + expected_output='A compelling 3 paragraphs blog post formatted as markdown about the latest AI advancements in 2025', + agent=writer, + human_input=True +) + +# Instantiate your crew with a sequential process +crew = Crew( + agents=[researcher, writer], + tasks=[task1, task2], + verbose=True, + memory=True, + planning=True # Enable planning feature for the crew +) + +# Get your crew to work! +result = crew.kickoff() + +print("######################") +print(result) +``` \ No newline at end of file diff --git a/docs/pt-BR/learn/kickoff-async.mdx b/docs/pt-BR/learn/kickoff-async.mdx new file mode 100644 index 000000000..d52639c45 --- /dev/null +++ b/docs/pt-BR/learn/kickoff-async.mdx @@ -0,0 +1,123 @@ +--- +title: Inicie uma Crew de Forma Assíncrona +description: Inicie uma Crew de Forma Assíncrona +icon: rocket-launch +--- + +## Introdução + +A CrewAI oferece a capacidade de iniciar uma crew de forma assíncrona, permitindo que você comece a execução da crew de maneira não bloqueante. +Esse recurso é especialmente útil quando você deseja executar múltiplas crews simultaneamente ou quando precisa realizar outras tarefas enquanto a crew está em execução. + +## Execução Assíncrona de Crew + +Para iniciar uma crew de forma assíncrona, utilize o método `kickoff_async()`. Este método inicia a execução da crew em uma thread separada, permitindo que a thread principal continue executando outras tarefas. + +### Assinatura do Método + +```python Code +def kickoff_async(self, inputs: dict) -> CrewOutput: +``` + +### Parâmetros + +- `inputs` (dict): Um dicionário contendo os dados de entrada necessários para as tarefas. + +### Retorno + +- `CrewOutput`: Um objeto que representa o resultado da execução da crew. + +## Possíveis Casos de Uso + +- **Geração Paralela de Conteúdo**: Inicie múltiplas crews independentes de forma assíncrona, cada uma responsável por gerar conteúdo sobre temas diferentes. Por exemplo, uma crew pode pesquisar e redigir um artigo sobre tendências em IA, enquanto outra gera posts para redes sociais sobre o lançamento de um novo produto. Cada crew atua de forma independente, permitindo a escala eficiente da produção de conteúdo. + +- **Tarefas Conjuntas de Pesquisa de Mercado**: Lance múltiplas crews de forma assíncrona para realizar pesquisas de mercado em paralelo. Uma crew pode analisar tendências do setor, outra examinar estratégias de concorrentes e ainda outra avaliar o sentimento do consumidor. Cada crew conclui sua tarefa de forma independente, proporcionando insights mais rápidos e abrangentes. + +- **Módulos Independentes de Planejamento de Viagem**: Execute crews separadas para planejar diferentes aspectos de uma viagem de forma independente. Uma crew pode cuidar das opções de voo, outra das acomodações e uma terceira do planejamento das atividades. Cada crew trabalha de maneira assíncrona, permitindo que os vários componentes da viagem sejam planejados ao mesmo tempo e de maneira independente, para resultados mais rápidos. + +## Exemplo: Execução Assíncrona de uma Única Crew + +Veja um exemplo de como iniciar uma crew de forma assíncrona utilizando asyncio e aguardando o resultado: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +# Create an agent with code execution enabled +coding_agent = Agent( + role="Python Data Analyst", + goal="Analyze data and provide insights using Python", + backstory="You are an experienced data analyst with strong Python skills.", + allow_code_execution=True +) + +# Create a task that requires code execution +data_analysis_task = Task( + description="Analyze the given dataset and calculate the average age of participants. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +# Create a crew and add the task +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +# Async function to kickoff the crew asynchronously +async def async_crew_execution(): + result = await analysis_crew.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + +# Run the async function +asyncio.run(async_crew_execution()) +``` + +## Exemplo: Execução Assíncrona de Múltiplas Crews + +Neste exemplo, mostraremos como iniciar múltiplas crews de forma assíncrona e aguardar todas serem concluídas usando `asyncio.gather()`: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +# Create an agent with code execution enabled +coding_agent = Agent( + role="Python Data Analyst", + goal="Analyze data and provide insights using Python", + backstory="You are an experienced data analyst with strong Python skills.", + allow_code_execution=True +) + +# Create tasks that require code execution +task_1 = Task( + description="Analyze the first dataset and calculate the average age of participants. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +task_2 = Task( + description="Analyze the second dataset and calculate the average age of participants. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +# Create two crews and add tasks +crew_1 = Crew(agents=[coding_agent], tasks=[task_1]) +crew_2 = Crew(agents=[coding_agent], tasks=[task_2]) + +# Async function to kickoff multiple crews asynchronously and wait for all to finish +async def async_multiple_crews(): + # Create coroutines for concurrent execution + result_1 = crew_1.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]}) + result_2 = crew_2.kickoff_async(inputs={"ages": [20, 22, 24, 28, 30]}) + + # Wait for both crews to finish + results = await asyncio.gather(result_1, result_2) + + for i, result in enumerate(results, 1): + print(f"Crew {i} Result:", result) + +# Run the async function +asyncio.run(async_multiple_crews()) +``` \ No newline at end of file diff --git a/docs/pt-BR/learn/kickoff-for-each.mdx b/docs/pt-BR/learn/kickoff-for-each.mdx new file mode 100644 index 000000000..7fcc7bcf4 --- /dev/null +++ b/docs/pt-BR/learn/kickoff-for-each.mdx @@ -0,0 +1,53 @@ +--- +title: Kickoff Crew para Cada +description: Kickoff Crew para Cada Item em uma Lista +icon: at +--- + +## Introdução + +A CrewAI oferece a capacidade de iniciar um crew para cada item em uma lista, permitindo que você execute o crew para cada item da lista. +Esse recurso é particularmente útil quando é necessário realizar o mesmo conjunto de tarefas para vários itens. + +## Iniciando um Crew para Cada Item + +Para iniciar um crew para cada item em uma lista, utilize o método `kickoff_for_each()`. +Esse método executa o crew para cada item da lista, permitindo o processamento eficiente de múltiplos itens. + +Veja um exemplo de como iniciar um crew para cada item em uma lista: + +```python Code +from crewai import Crew, Agent, Task + +# Create an agent with code execution enabled +coding_agent = Agent( + role="Python Data Analyst", + goal="Analyze data and provide insights using Python", + backstory="You are an experienced data analyst with strong Python skills.", + allow_code_execution=True +) + +# Create a task that requires code execution +data_analysis_task = Task( + description="Analyze the given dataset and calculate the average age of participants. Ages: {ages}", + agent=coding_agent, + expected_output="The average age calculated from the dataset" +) + +# Create a crew and add the task +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task], + verbose=True, + memory=False +) + +datasets = [ + { "ages": [25, 30, 35, 40, 45] }, + { "ages": [20, 25, 30, 35, 40] }, + { "ages": [30, 35, 40, 45, 50] } +] + +# Execute the crew +result = analysis_crew.kickoff_for_each(inputs=datasets) +``` \ No newline at end of file diff --git a/docs/pt-BR/learn/llm-connections.mdx b/docs/pt-BR/learn/llm-connections.mdx new file mode 100644 index 000000000..39bf98660 --- /dev/null +++ b/docs/pt-BR/learn/llm-connections.mdx @@ -0,0 +1,204 @@ +--- +title: Conecte-se a qualquer LLM +description: Guia abrangente sobre como integrar o CrewAI a diversos Large Language Models (LLMs) usando o LiteLLM, incluindo provedores compatíveis e opções de configuração. +icon: brain-circuit +--- + +## Conecte o CrewAI a LLMs + +O CrewAI utiliza o LiteLLM para conectar-se a uma grande variedade de Modelos de Linguagem (LLMs). Essa integração proporciona grande versatilidade, permitindo que você utilize modelos de inúmeros provedores por meio de uma interface simples e unificada. + + + Por padrão, o CrewAI usa o modelo `gpt-4o-mini`. Isso é determinado pela variável de ambiente `OPENAI_MODEL_NAME`, que tem como padrão "gpt-4o-mini" se não for definida. + Você pode facilmente configurar seus agentes para usar um modelo ou provedor diferente, conforme descrito neste guia. + + +## Provedores Compatíveis + +O LiteLLM oferece suporte a uma ampla gama de provedores, incluindo, mas não se limitando a: + +- OpenAI +- Anthropic +- Google (Vertex AI, Gemini) +- Azure OpenAI +- AWS (Bedrock, SageMaker) +- Cohere +- VoyageAI +- Hugging Face +- Ollama +- Mistral AI +- Replicate +- Together AI +- AI21 +- Cloudflare Workers AI +- DeepInfra +- Groq +- SambaNova +- [NVIDIA NIMs](https://docs.api.nvidia.com/nim/reference/models-1) +- E muitos outros! + +Para uma lista completa e sempre atualizada dos provedores suportados, consulte a [documentação de Provedores do LiteLLM](https://docs.litellm.ai/docs/providers). + +## Alterando a LLM + +Para utilizar uma LLM diferente com seus agentes CrewAI, você tem várias opções: + + + + Passe o nome do modelo como uma string ao inicializar o agente: + + ```python Code + from crewai import Agent + + # Usando o GPT-4 da OpenAI + openai_agent = Agent( + role='OpenAI Expert', + goal='Provide insights using GPT-4', + backstory="An AI assistant powered by OpenAI's latest model.", + llm='gpt-4' + ) + + # Usando o Claude da Anthropic + claude_agent = Agent( + role='Anthropic Expert', + goal='Analyze data using Claude', + backstory="An AI assistant leveraging Anthropic's language model.", + llm='claude-2' + ) + ``` + + + + Para uma configuração mais detalhada, utilize a classe LLM: + + ```python Code + from crewai import Agent, LLM + + llm = LLM( + model="gpt-4", + temperature=0.7, + base_url="https://api.openai.com/v1", + api_key="your-api-key-here" + ) + + agent = Agent( + role='Customized LLM Expert', + goal='Provide tailored responses', + backstory="An AI assistant with custom LLM settings.", + llm=llm + ) + ``` + + + + +## Opções de Configuração + +Ao configurar uma LLM para o seu agente, você tem acesso a uma variedade de parâmetros: + +| Parâmetro | Tipo | Descrição | +|:----------|:-----:|:-------------| +| **model** | `str` | O nome do modelo a ser utilizado (ex.: "gpt-4", "claude-2") | +| **temperature** | `float` | Controla o grau de aleatoriedade nas respostas (0.0 a 1.0) | +| **max_tokens** | `int` | Número máximo de tokens a serem gerados | +| **top_p** | `float` | Controla a diversidade das respostas (0.0 a 1.0) | +| **frequency_penalty** | `float` | Penaliza novos tokens com base na frequência em que já apareceram no texto | +| **presence_penalty** | `float` | Penaliza novos tokens com base na presença deles no texto até o momento | +| **stop** | `str`, `List[str]` | Sequência(s) que interrompem a geração do texto | +| **base_url** | `str` | URL base do endpoint da API | +| **api_key** | `str` | Sua chave de API para autenticação | + +Para uma lista completa de parâmetros e suas respectivas descrições, consulte a documentação da classe LLM. + +## Conectando-se a LLMs Compatíveis com OpenAI + +Você pode se conectar a LLMs compatíveis com a OpenAI usando variáveis de ambiente ou definindo atributos específicos na classe LLM: + + + + + ```python Generic + import os + + os.environ["OPENAI_API_KEY"] = "your-api-key" + os.environ["OPENAI_API_BASE"] = "https://api.your-provider.com/v1" + os.environ["OPENAI_MODEL_NAME"] = "your-model-name" + ``` + + ```python Google + import os + + # Exemplo usando a API compatível com OpenAI do Gemini. + os.environ["OPENAI_API_KEY"] = "your-gemini-key" # Deve começar com AIza... + os.environ["OPENAI_API_BASE"] = "https://generativelanguage.googleapis.com/v1beta/openai/" + os.environ["OPENAI_MODEL_NAME"] = "openai/gemini-2.0-flash" # Adicione aqui seu modelo do Gemini, sob openai/ + ``` + + + + + ```python Generic + llm = LLM( + model="custom-model-name", + api_key="your-api-key", + base_url="https://api.your-provider.com/v1" + ) + agent = Agent(llm=llm, ...) + ``` + + ```python Google + # Exemplo usando a API compatível com OpenAI do Gemini + llm = LLM( + model="openai/gemini-2.0-flash", + base_url="https://generativelanguage.googleapis.com/v1beta/openai/", + api_key="your-gemini-key", # Deve começar com AIza... + ) + agent = Agent(llm=llm, ...) + ``` + + + + +## Utilizando Modelos Locais com Ollama + +Para modelos locais como os oferecidos pelo Ollama: + + + + [Clique aqui para baixar e instalar o Ollama](https://ollama.com/download) + + + Por exemplo, execute `ollama pull llama3.2` para baixar o modelo. + + + + ```python Code + agent = Agent( + role='Local AI Expert', + goal='Process information using a local model', + backstory="An AI assistant running on local hardware.", + llm=LLM(model="ollama/llama3.2", base_url="http://localhost:11434") + ) + ``` + + + + +## Alterando a URL Base da API + +Você pode alterar a URL base da API para qualquer provedor de LLM definindo o parâmetro `base_url`: + +```python Code +llm = LLM( + model="custom-model-name", + base_url="https://api.your-provider.com/v1", + api_key="your-api-key" +) +agent = Agent(llm=llm, ...) +``` + +Isso é particularmente útil ao trabalhar com APIs compatíveis com a OpenAI ou quando você precisa especificar um endpoint diferente para o provedor escolhido. + +## Conclusão + +Ao utilizar o LiteLLM, o CrewAI oferece integração transparente com uma vasta gama de LLMs. Essa flexibilidade permite que você escolha o modelo mais adequado para sua necessidade específica, seja priorizando desempenho, custo-benefício ou implantação local. Lembre-se de consultar a [documentação do LiteLLM](https://docs.litellm.ai/docs/) para obter as informações mais atualizadas sobre modelos suportados e opções de configuração. \ No newline at end of file diff --git a/docs/pt-BR/learn/llm-selection-guide.mdx b/docs/pt-BR/learn/llm-selection-guide.mdx new file mode 100644 index 000000000..44896ff9d --- /dev/null +++ b/docs/pt-BR/learn/llm-selection-guide.mdx @@ -0,0 +1,727 @@ +--- +title: 'Guia Estratégico de Seleção de LLMs' +description: 'Framework estratégico para escolher o LLM certo para seus agentes CrewAI e escrever definições eficazes de tarefas e agentes' +icon: 'brain-circuit' +--- + +## A Abordagem CrewAI para Seleção de LLMs + +Em vez de recomendações prescritivas de modelos, defendemos um **framework de pensamento** que ajude você a tomar decisões informadas com base no seu caso de uso, restrições e requisitos específicos. O cenário de LLMs evolui rapidamente, com novos modelos surgindo regularmente e os existentes sendo atualizados frequentemente. O que mais importa é desenvolver uma abordagem sistemática de avaliação que permaneça relevante independentemente dos modelos disponíveis no momento. + + +Este guia foca em pensamento estratégico em vez de recomendações de modelos específicos, já que o cenário dos LLMs evolui rapidamente. + + +## Framework de Decisão Rápida + + + + Comece entendendo profundamente o que suas tarefas realmente exigem. Considere a complexidade cognitiva envolvida, a profundidade de raciocínio necessária, o formato dos resultados esperados e a quantidade de contexto que o modelo precisará processar. Essa análise fundamental guiará todas as decisões seguintes. + + + Assim que você compreende seus requisitos, mapeie-os para as forças dos modelos. Diferentes famílias de modelos se destacam em diferentes tipos de trabalho; alguns são otimizados para raciocínio e análise, outros para criatividade e geração de conteúdo, e outros para velocidade e eficiência. + + + Leve em conta suas reais restrições operacionais, incluindo limitações orçamentárias, requisitos de latência, necessidades de privacidade de dados e capacidades de infraestrutura. O melhor modelo teoricamente pode não ser a melhor escolha prática para sua situação. + + + Comece com modelos confiáveis e bem conhecidos e otimize com base no desempenho real no seu caso de uso. Os resultados práticos frequentemente diferem dos benchmarks teóricos, então testes empíricos são cruciais. + + + +## Framework Central de Seleção + +### a. Pensamento Orientado à Tarefa + +O passo mais crítico na seleção de LLMs é entender o que sua tarefa realmente exige. Frequentemente, equipes escolhem modelos com base em reputação geral ou pontuações de benchmark, sem analisar cuidadosamente suas necessidades específicas. Essa abordagem leva tanto ao superdimensionamento de tarefas simples usando modelos caros e complexos quanto à subutilização em tarefas sofisticadas com modelos sem as capacidades necessárias. + + + + - **Tarefas Simples** representam a maioria do trabalho diário de IA e incluem seguir instruções básicas, processar dados simples e formatação elementar. Estas tarefas geralmente têm entradas e saídas claras, com mínima ambiguidade. A carga cognitiva é baixa e o modelo precisa apenas seguir instruções explícitas, não realizar raciocínio complexo. + + - **Tarefas Complexas** exigem raciocínio de múltiplas etapas, pensamento estratégico e a capacidade de lidar com informações ambíguas ou incompletas. Podem envolver análise de múltiplas fontes de dados, desenvolvimento de estratégias abrangentes ou resolução de problemas que precisam ser decompostos em componentes menores. O modelo deve manter o contexto ao longo de várias etapas de raciocínio e frequentemente precisa inferir informações não explicitamente declaradas. + + - **Tarefas Criativas** exigem um tipo diferente de capacidade cognitiva, focada em gerar conteúdo novo, envolvente e adequado ao contexto. Isso inclui storytelling, criação de textos de marketing e solução criativa de problemas. O modelo deve compreender nuances, tom e público, produzindo conteúdo autêntico e envolvente, não apenas fórmulas. + + + + - **Dados Estruturados** exigem precisão e consistência na adesão ao formato. Ao trabalhar com JSON, XML ou formatos de banco de dados, o modelo deve produzir saídas sintaticamente corretas, que possam ser processadas programaticamente. Essas tarefas possuem requisitos rígidos de validação e pouca tolerância a erros de formato, tornando a confiabilidade mais importante que a criatividade. + + - **Conteúdo Criativo** requer equilíbrio entre competência técnica e criatividade. O modelo precisa compreender o público, tom e voz da marca, ao mesmo tempo em que produz conteúdo que engaja leitores e atinge objetivos comunicativos específicos. A qualidade aqui é mais subjetiva e exige modelos capazes de adaptar o estilo de escrita a diferentes contextos e propósitos. + + - **Conteúdo Técnico** situa-se entre dados estruturados e conteúdo criativo, demandando precisão e clareza. Documentação, geração de código e análises técnicas precisam ser exatas e completas, mas ainda assim acessíveis ao público-alvo. O modelo deve entender conceitos técnicos complexos e comunicá-los de forma eficaz. + + + + - **Contexto Curto** envolve tarefas imediatas e focalizadas, onde o modelo processa informações limitadas rapidamente. São interações transacionais em que velocidade e eficiência importam mais do que compreensão profunda. O modelo não precisa manter histórico extenso ou processar grandes documentos. + + - **Contexto Longo** é necessário ao lidar com documentos substanciais, conversas extensas ou tarefas complexas de múltiplas partes. O modelo precisa manter coerência ao longo de milhares de tokens, referenciando informações anteriores com precisão. Essencial para análise de documentos, pesquisa abrangente e sistemas de diálogo sofisticados. + + - **Contexto Muito Longo** ultrapassa os limites do possível hoje, com processamento de documentos massivos, síntese de pesquisas extensas ou interações multi-sessão. São casos que exigem modelos projetados especificamente para lidar com contexto estendido e envolvem trade-offs entre extensão e velocidade. + + + +### b. Mapeamento de Capacidades do Modelo + +Entender as capacidades dos modelos exige ir além do marketing e dos benchmarks, analisando forças e limitações fundamentais das arquiteturas e métodos de treinamento. + + + + Modelos de raciocínio formam uma categoria especializada, projetada para tarefas de pensamento complexo e de múltiplas etapas. Eles se destacam na resolução de problemas que requerem análise cuidadosa, planejamento estratégico ou decomposição sistemática. Normalmente aplicam técnicas como chain-of-thought ou tree-of-thought para conduzir o raciocínio passo a passo. + + O ponto forte é manter consistência lógica em cadeias longas de raciocínio e decompor problemas complexos em partes gerenciáveis. São especialmente valiosos para planejamento estratégico, análise complexa e situações onde a qualidade do raciocínio importa mais que a velocidade. + + Entretanto, há trade-offs em termos de custo e velocidade. Podem ser menos adequados para tarefas criativas ou operações simples, onde suas capacidades avançadas não são necessárias. Considere-os quando as tarefas realmente se beneficiarem dessa análise detalhada. + + + + Modelos de uso geral oferecem uma abordagem equilibrada, com desempenho sólido em uma ampla gama de tarefas, sem especialização extrema. São treinados em conjuntos de dados diversificados e otimizados para versatilidade. + + A principal vantagem é a confiabilidade previsível em diversos trabalhos: pesquisa, análise, criação de conteúdo, processamento de dados. São ótimas opções iniciais para equipes que buscam consistência ao lidar com fluxos variados. + + Embora não atinjam picos de desempenho como modelos especializados, oferecem simplicidade operacional e baixa complexidade na gestão. São o melhor ponto de partida para novos projetos, permitindo descobertas de necessidades antes de avançar para otimizações. + + + + Modelos rápidos e eficientes priorizam velocidade, custo e eficiência de recursos, em vez de raciocínio sofisticado. São otimizados para cenários de alto volume onde respostas rápidas e baixos custos são mais importantes que compreensão ou criatividade profunda. + + Brilham em operações rotineiras, processamento simples de dados, chamadas de funções e tarefas de alto volume. Aplicações que processam muitos pedidos rapidamente ou operam sob restrições orçamentárias se beneficiam desses modelos. + + O ponto crucial é garantir que suas capacidades atendam às exigências da tarefa. Podem não atender tarefas que exijam entendimento profundo, raciocínio complexo ou geração de conteúdo sofisticado. São ideais para tarefas rotineiras bem definidas. + + + + Modelos criativos são otimizados para geração de conteúdo, qualidade de escrita e pensamento inovador. Excelentes na compreensão de nuances, tom e estilo, produzindo conteúdo envolvente e natural. + + O ponto forte está em adaptar o estilo para diferentes públicos, manter voz e tom consistentes e engajar leitores. Performam melhor em storytelling, textos publicitários, comunicações de marca e outras tarefas com criatividade como foco. + + Ao selecionar esses modelos, considere não apenas a habilidade de gerar texto, mas a compreensão de público, contexto e objetivo. Os melhores modelos criativos adaptam a saída à voz da marca, diferentes segmentos e mantêm consistência em peças longas. + + + + Modelos open source oferecem vantagens em controle de custos, potencial de customização, privacidade de dados e flexibilidade de deployment. Podem ser rodados localmente ou em infraestrutura própria, dando controle total sobre dados e comportamento. + + Os principais benefícios incluem eliminação de custos por token, possibilidade de fine-tuning, privacidade total e independência de fornecedores externos. Perfeitos para organizações com necessidade de privacidade, orçamento limitado ou desejo de customização. + + Contudo, requerem maior expertise técnica para implantar e manter. Considere custos de infraestrutura, complexidade de gestão e esforços contínuos de atualização e otimização ao avaliar modelos open source. O custo total pode ser maior que o de alternativas em nuvem devido a esse overhead. + + + +## Padrões Estratégicos de Configuração + +### a. Abordagem Multi-Modelo + + +Use diferentes modelos para diferentes propósitos dentro da mesma crew para otimizar desempenho e custos. + + +As implementações CrewAI mais sofisticadas empregam múltiplos modelos estrategicamente, designando-os conforme as funções e necessidades dos agentes. Assim, é possível otimizar desempenho e custos usando o modelo mais adequado para cada tipo de tarefa. + +Agentes de planejamento se beneficiam de modelos de raciocínio para pensamento estratégico e análise multi-etapas. Esses agentes funcionam como o "cérebro" da operação. Agentes de conteúdo têm melhor desempenho com modelos criativos focados em qualidade de escrita e engajamento. Agentes de processamento, responsáveis por operações rotineiras, podem usar modelos eficientes priorizando velocidade. + +**Exemplo: Crew de Pesquisa e Análise** + +```python +from crewai import Agent, Task, Crew, LLM + +# Modelo de raciocínio para planejamento estratégico +manager_llm = LLM(model="gemini-2.5-flash-preview-05-20", temperature=0.1) + +# Modelo criativo para gerar conteúdo +content_llm = LLM(model="claude-3-5-sonnet-20241022", temperature=0.7) + +# Modelo eficiente para processamento de dados +processing_llm = LLM(model="gpt-4o-mini", temperature=0) + +research_manager = Agent( + role="Research Strategy Manager", + goal="Develop comprehensive research strategies and coordinate team efforts", + backstory="Expert research strategist with deep analytical capabilities", + llm=manager_llm, # Modelo de alto nível para raciocínio complexo + verbose=True +) + +content_writer = Agent( + role="Research Content Writer", + goal="Transform research findings into compelling, well-structured reports", + backstory="Skilled writer who excels at making complex topics accessible", + llm=content_llm, # Modelo criativo para conteúdo envolvente + verbose=True +) + +data_processor = Agent( + role="Data Analysis Specialist", + goal="Extract and organize key data points from research sources", + backstory="Detail-oriented analyst focused on accuracy and efficiency", + llm=processing_llm, # Modelo rápido para tarefas rotineiras + verbose=True +) + +crew = Crew( + agents=[research_manager, content_writer, data_processor], + tasks=[...], # Suas tarefas específicas + manager_llm=manager_llm, # Manager usa o modelo de raciocínio + verbose=True +) +``` + +O segredo do sucesso na implementação multi-modelo está em entender como os agentes interagem e garantir que as capacidades dos modelos estejam alinhadas às responsabilidades. Isso exige planejamento estratégico, mas traz ganhos significativos em qualidade dos resultados e eficiência operacional. + +### b. Seleção Específica por Componente + + + + O manager LLM desempenha papel central em fluxos hierárquicos CrewAI, coordenando agentes e tarefas. Este modelo precisa se destacar em delegação, priorização de tarefas e manutenção de contexto em várias operações simultâneas. + + LLMs de manager eficazes exigem forte raciocínio para delegar bem, desempenho consistente para coordenar previsivelmente e excelente gestão de contexto para acompanhar o estado dos agentes. O modelo deve entender capacidades e limitações dos agentes enquanto otimiza a alocação de tarefas. + + O custo é especialmente relevante, já que este LLM participa de todas as operações. O modelo precisa entregar capacidades suficientes, sem o preço premium de opções sofisticadas demais, buscando sempre o equilíbrio entre performance e valor. + + + + LLMs de function calling gerenciam o uso de ferramentas por todos os agentes, sendo críticos em crews que dependem fortemente de APIs externas e ferramentas. Devem ser precisos na extração de parâmetros e no processamento das respostas. + + As características mais importantes são precisão e confiabilidade, não criatividade ou raciocínio avançado. O modelo deve extrair parâmetros corretos de comandos em linguagem natural consistentemente e processar respostas de ferramentas adequadamente. Velocidade também importa, pois o uso de ferramentas pode envolver múltiplas idas e vindas de informação. + + Muitas equipes descobrem que modelos especializados em function calling ou de uso geral com forte suporte a ferramentas funcionam melhor do que modelos criativos ou de raciocínio nesse papel. O fundamental é assegurar que o modelo consiga converter instruções em chamadas estruturadas sem falhas. + + + + Agentes individuais podem sobrescrever o LLM do nível da crew quando suas necessidades diferem significativamente das do restante. Isso permite otimização pontual, mantendo a simplicidade operacional para os demais agentes. + + Considere sobrescritas quando a função do agente exige capacidades distintas. Por exemplo, um agente de redação criativa pode se beneficiar de um LLM otimizado para geração de conteúdo, enquanto um analista de dados pode preferir um modelo voltado ao raciocínio. + + O desafio é balancear otimização com complexidade operacional. Cada modelo adicional aumenta a complexidade de deployment, monitoramento e custos. Foque em sobrescritas apenas quando a melhoria justificar essa complexidade. + + + +## Framework de Definição de Tarefas + +### a. Foque em Clareza, Não em Complexidade + +Definir bem as tarefas é frequentemente mais importante do que a seleção do modelo no resultado gerado pelos agentes CrewAI. Tarefas bem formuladas orientam claramente mesmo modelos simples a terem bom desempenho. Já tarefas mal definidas prejudicam até os modelos mais avançados. + + + + As melhores descrições de tarefas equilibram detalhamento e clareza. Devem definir o objetivo de forma clara e sem ambiguidade, além de explicar o método a ser usado com detalhes que permitam ao agente agir corretamente. + + Descrições eficazes incluem contexto relevante e restrições, ajudando o agente a entender o propósito maior e quaisquer limitações. Divida trabalhos complexos em etapas gerenciáveis em vez de objetivos genéricos e sobrecarregados. + + Erros comuns incluem objetivos vagos, falta de contexto, critérios de sucesso mal definidos ou mistura de tarefas totalmente distintas em um mesmo texto. O objetivo é passar informação suficiente para o sucesso, mas mantendo foco no resultado claro. + + + + As diretrizes da saída esperada funcionam como contrato entre definição de tarefa e agente, especificando claramente o que deve ser entregue e como será avaliado. Elas abrangem formato, estrutura e elementos essenciais. + + As melhores diretrizes incluem exemplos concretos de indicadores de qualidade e critérios claros de conclusão, de modo que agente e revisores humanos possam avaliar o resultado facilmente. Isso reduz ambiguidades e garante resultados consistentes. + + Evite descrições genéricas que serviriam para qualquer tarefa, ausência de especificações de formato, padrões vagos ou falta de exemplos/modelos que ajudem o agente a entender as expectativas. + + + +### b. Estratégia de Sequenciamento de Tarefas + + + + Dependências são essenciais quando as tarefas se baseiam em resultados prévios, informações fluem de uma tarefa para outra, ou a qualidade depende da conclusão de fases anteriores. Assim, cada tarefa recebe o contexto correto para o sucesso. + + Para implementar bem, use o parâmetro de contexto para encadear tarefas, desenvolvendo gradualmente a complexidade. Cada tarefa deve gerar saídas que alimentam as próximas. O objetivo é manter um fluxo lógico entre as tarefas dependentes, evitando gargalos desnecessários. + + Funciona melhor quando há progressão lógica evidente e quando a saída de uma tarefa realmente agrega valor nas etapas seguintes. Cuidado com os gargalos; foque nas dependências essenciais. + + + + A execução paralela é valiosa quando as tarefas são independentes, o tempo é crítico ou há expertise distintas que não exigem coordenação. Pode reduzir drasticamente o tempo total, permitindo que agentes especializados atuem simultaneamente. + + Para isso, identifique tarefas realmente independentes, agrupe fluxos de trabalho distintos e planeje a integração dos resultados posteriormente. O ponto-chave é garantir que tarefas paralelas não gerem conflitos ou redundâncias. + + Considere o paralelo em múltiplos fluxos independentes, diferentes tipos de análise autônoma, ou criação de conteúdo que pode ser feita ao mesmo tempo. Mas atente-se à alocação de recursos, evitando sobrecarga de modelos ou estouro no orçamento. + + + +## Otimizando a Configuração dos Agentes para Desempenho de LLMs + +### a. Seleção de LLM Guiada pelo Papel + + +Funções genéricas de agentes tornam impossível escolher o LLM certo. Funções específicas permitem otimização do modelo conforme a função. + + +A especificidade das funções dos agentes determina quais capacidades de LLM mais importam para alto desempenho, criando oportunidade estratégica de alinhar forças do modelo ao papel do agente. + +**Impacto de Funções Genéricas vs. Específicas:** + +Ao definir funções, pense no conhecimento do domínio, estilo de trabalho e frameworks decisórios mais valiosos para o tipo de tarefa do agente. Quanto mais específica e contextualizada a função, melhor o modelo incorporará esse papel. +```python +# ✅ Função específica - requisitos claros de LLM +specific_agent = Agent( + role="SaaS Revenue Operations Analyst", # Expertise de domínio clara + goal="Analyze recurring revenue metrics and identify growth opportunities", + backstory="Specialist in SaaS business models with deep understanding of ARR, churn, and expansion revenue", + llm=LLM(model="gpt-4o") # Raciocínio justificado para análise complexa +) +``` + +**Estratégia de Mapeamento de Função para Modelo:** + +- **"Research Analyst"** → Modelo de raciocínio (GPT-4o, Claude Sonnet) para análise complexa +- **"Content Editor"** → Modelo criativo (Claude, GPT-4o) para qualidade de escrita +- **"Data Processor"** → Modelo eficiente (GPT-4o-mini, Gemini Flash) para tarefas estruturadas +- **"API Coordinator"** → Modelo otimizado para function calling (GPT-4o, Claude) para uso de ferramentas + +### b. Backstory como Amplificador de Contexto do Modelo + + +Backstories estratégicos maximizam a eficácia do LLM ao contextualizar as respostas de forma que prompts genéricos não conseguem. + + +Um bom backstory transforma a escolha do LLM de genérica a especializada. Isso é crucial para otimizar custos: um modelo eficiente com contexto certo pode superar um premium sem contexto. + +**Exemplo de Performance Guiada por Contexto:** + +```python +# Contexto amplifica a efetividade do modelo +domain_expert = Agent( + role="B2B SaaS Marketing Strategist", + goal="Develop comprehensive go-to-market strategies for enterprise software", + backstory=""" + You have 10+ years of experience scaling B2B SaaS companies from Series A to IPO. + You understand the nuances of enterprise sales cycles, the importance of product-market + fit in different verticals, and how to balance growth metrics with unit economics. + You've worked with companies like Salesforce, HubSpot, and emerging unicorns, giving + you perspective on both established and disruptive go-to-market strategies. + """, + llm=LLM(model="claude-3-5-sonnet", temperature=0.3) # Criatividade balanceada com conhecimento de domínio +) + +# Esse contexto faz o Claude agir como especialista do setor +# Sem isso, mesmo ele entregaria respostas genéricas +``` + +**Elementos de Backstory que Potencializam a Performance de LLMs:** +- **Experiência de Domínio**: "10+ anos em vendas enterprise SaaS" +- **Expertise Específica**: "Especialista em due diligence técnica para Série B+" +- **Estilo de Trabalho**: "Decisões orientadas a dados, documentação clara" +- **Padrões de Qualidade**: "Sempre cita fontes e mostra análise detalhada" + +### c. Otimização Holística de Agente + LLM + +As configurações mais eficazes criam sinergia entre função específica, profundidade do backstory e escolha do LLM. Cada elemento reforça o outro para maximizar rendimento. + +**Framework de Otimização:** + +```python +# Exemplo: Agente de Documentação Técnica +tech_writer = Agent( + role="API Documentation Specialist", + goal="Create comprehensive, developer-friendly API documentation", + backstory=""" + You're a technical writer with 8+ years documenting REST APIs, GraphQL endpoints, + and SDK integration guides. You've worked with developer tools companies and + understand what developers need: clear examples, comprehensive error handling, + and practical use cases. You prioritize accuracy and usability over marketing fluff. + """, + llm=LLM( + model="claude-3-5-sonnet", + temperature=0.1 + ), + tools=[code_analyzer_tool, api_scanner_tool], + verbose=True +) +``` + +**Checklist de Alinhamento:** +- ✅ **Função Específica**: Domínio e responsabilidades claras +- ✅ **Correspondência do LLM**: Forças do modelo conectadas à função +- ✅ **Profundidade do Backstory**: Contexto de domínio disponível pro modelo +- ✅ **Integração de Ferramentas**: Ferramentas fortalecem a função do agente +- ✅ **Ajuste de Parâmetros**: Temperatura e configs otimizadas para a função + +O segredo é criar agentes onde cada configuração reforça sua estratégia de escolha do LLM, maximizando rendimento e otimizando custos. + +## Checklist Prático de Implementação + +Em vez de repetir o framework estratégico, segue um checklist tático para implementar as decisões de seleção de LLM em CrewAI: + + + + **O que analisar:** + - Todos os agentes usam o mesmo LLM por padrão? + - Quais agentes lidam com tarefas mais complexas? + - Quais agentes só processam ou formatam dados? + - Algum agente depende fortemente de ferramentas? + + **Ação**: Documente funções dos agentes e identifique oportunidades de otimização. + + + + **Defina sua Base:** + ```python + # Comece com um padrão confiável para a crew + default_crew_llm = LLM(model="gpt-4o-mini") # Base econômica + + crew = Crew( + agents=[...], + tasks=[...], + memory=True + ) + ``` + + **Ação**: Defina o LLM padrão da crew antes de otimizar agentes individuais. + + + + **Identifique e Aprimore Agentes-Chave:** + ```python + # Agentes gerenciadores ou de coordenação + manager_agent = Agent( + role="Project Manager", + llm=LLM(model="gemini-2.5-flash-preview-05-20"), + # ... demais configs + ) + + # Agentes criativos ou customer-facing + content_agent = Agent( + role="Content Creator", + llm=LLM(model="claude-3-5-sonnet"), + # ... demais configs + ) + ``` + + **Ação**: Faça upgrade dos 20% dos agentes que tratam 80% da complexidade. + + + + **Após colocar os agentes em produção:** + - Use [CrewAI Enterprise platform](https://app.crewai.com) para testar seleções de modelo A/B + - Execute múltiplas iterações com inputs reais para medir consistência e performance + - Compare custo vs performance na configuração otimizada + - Compartilhe resultados com o time para tomada coletiva de decisão + + **Ação**: Substitua achismos por validação com dados reais usando a plataforma de testes. + + + +### Quando Usar Tipos Diferentes de Modelos + + + + Modelos de raciocínio tornam-se essenciais quando tarefas exigem pensamento lógico genuíno em múltiplas etapas, planejamento estratégico ou decisões complexas beneficiadas por análise sistemática. Brilham na decomposição de problemas e análise estruturada, não no simples seguimento de padrões. + + Considere-os para desenvolvimento de estratégias de negócios, análise de dados combinados de múltiplas fontes, resolução de problemas dependente de etapas sucessivas e planejamento estratégico envolvendo múltiplas variáveis. + + Entretanto, esses modelos são mais caros e lentos, devendo ser reservados para tarefas onde suas capacidades agregam valor real — evite usá-los apenas para operações simples. + + + + Modelos criativos são valiosos quando a principal entrega é geração de conteúdo e a qualidade, estilo e engajamento desse conteúdo impactam o sucesso. Se destacam quando redação e estilo importam, ideação criativa é necessária, ou voz de marca é fundamental. + + Use-os em redação de posts, criação de artigos, textos de marketing com viés persuasivo, storytelling e comunicações da marca. Costumam captar nuances e contexto melhor do que generalistas. + + Podem ser menos adequados para tarefas técnicas ou analíticas, onde precisão supera criatividade. Use-os quando aspectos comunicativos são fatores críticos de sucesso. + + + + Modelos eficientes são ideais para operações frequentes e rotineiras, onde velocidade e custo são prioridade. Trabalham melhor em tarefas com parâmetros bem definidos, sem necessidade de raciocínio avançado ou criatividade. + + Considere-os para processamento e transformação de dados, formatação simples, chamadas de funções (function calling) e operações em alto volume onde custo importa mais. + + O ponto crítico é verificar adequação à tarefa. Funcionam para muitos fluxos rotineiros, mas podem falhar se a tarefa exigir compreensão técnica ou raciocínio. + + + + Modelos open source são atraentes quando há restrição orçamentária, necessidade de privacidade, personalização especial ou exigência de deployment local. + + Considere para ferramentas internas de empresas, aplicações sensíveis, projetos onde não é possível usar APIs externas, casos com orçamento apertado ou requisitos de customização. + + Mas lembre-se: exigem mais expertise, manutenção e investimentos em infraestrutura. Avalie o custo total da operação ao avaliar esses modelos. + + + +## Armadilhas Comuns na Seleção de Modelos CrewAI + + + + **O problema**: Usar o mesmo LLM para todos os agentes, independentemente das funções. Prática padrão, mas raramente ótima. + + **Exemplo real**: Usar GPT-4o tanto para planejamento estratégico quanto para extração simples de dados. O manager precisa do raciocínio premium, mas o extrator poderia usar o GPT-4o-mini, muito mais barato. + + **Solução CrewAI**: Configure modelos específicos por agente: + ```python + # Agente estratégico recebe modelo premium + manager = Agent(role="Strategy Manager", llm=LLM(model="gpt-4o")) + + # Agente de processamento recebe modelo eficiente + processor = Agent(role="Data Processor", llm=LLM(model="gpt-4o-mini")) + ``` + + + + **O problema**: Não entender como funciona a hierarquia LLM da CrewAI — configurações conflitam entre crew, manager e agentes. + + **Exemplo real**: Configurar crew com Claude, mas agentes com GPT, gerando comportamento inconsistente e trocas desnecessárias. + + **Solução CrewAI**: Planeje a hierarquia estrategicamente: + ```python + crew = Crew( + agents=[agent1, agent2], + tasks=[task1, task2], + manager_llm=LLM(model="gpt-4o"), + process=Process.hierarchical + ) + + # Agentes herdam o LLM da crew, salvo sobrescrita + agent1 = Agent(llm=LLM(model="claude-3-5-sonnet")) + ``` + + + + **O problema**: Escolher modelos pela capacidade geral e ignorar o desempenho em function calling em workflows intensivos em ferramentas. + + **Exemplo real**: Selecionar modelo criativo para agente que só precisa chamar APIs e processar dados estruturados, resultando em má extração de parâmetros. + + **Solução CrewAI**: Priorize desempenho em function calling para agentes que usam ferramentas: + ```python + # Para agentes com muitas ferramentas + tool_agent = Agent( + role="API Integration Specialist", + tools=[search_tool, api_tool, data_tool], + llm=LLM(model="gpt-4o"), + # OU + llm=LLM(model="claude-3-5-sonnet") + ) + ``` + + + + **O problema**: Decidir configurações complexas de modelo com base em hipóteses não validadas nos fluxos e tarefas reais CrewAI. + + **Exemplo real**: Implementar lógica elaborada de troca de modelo por tipo de tarefa sem testar se os ganhos compensam a complexidade. + + **Solução CrewAI**: Comece simples e otimize baseado em dados reais: + ```python + # Comece assim + crew = Crew(agents=[...], tasks=[...], llm=LLM(model="gpt-4o-mini")) + + # Teste a performance e só depois otimize agentes específicos + # Use testes Enterprise para validar melhorias + ``` + + + + **O problema**: Não considerar como janela de contexto dos modelos interage com memória e compartilhamento de contexto entre agentes CrewAI. + + **Exemplo real**: Usar modelo de contexto curto para agentes que precisam manter histórico ao longo de múltiplas iterações ou equipes com comunicação extensiva agent-to-agent. + + **Solução CrewAI**: Alinhe capacidades de contexto ao padrão de comunicação da crew. + + + +## Estratégia de Teste e Iteração + + + + Comece com modelos de uso geral, confiáveis e amplamente suportados. Isso estabelece base estável para entender necessidades e expectativas de desempenho antes de otimizar para demandas especializadas. + + + Desenvolva métricas alinhadas ao seu caso de uso e metas de negócio, não apenas benchmarks gerais. Foque na mensuração de resultados relevantes ao seu sucesso. + + + Faça mudanças baseadas no desempenho observado no seu contexto, não apenas considerações teóricas ou recomendações genéricas. O desempenho prático costuma ser bem diferente dos benchmarks. + + + Avalie todo custo de operação, incluindo modelo, tempo de desenvolvimento, manutenção e complexidade. O modelo mais barato por token pode não ser o mais econômico ao considerar todos os fatores. + + + + +Foque em entender seus requisitos primeiro, e então escolha modelos que melhor correspondam a essas necessidades. O melhor LLM é aquele que consistentemente entrega os resultados esperados dentro das suas restrições. + + +### Validação de Modelos em Nível Enterprise + +Para equipes sérias sobre otimização, a **plataforma CrewAI Enterprise** oferece testes sofisticados que vão além do CLI. Ela permite avaliação completa para decisões orientadas por dados na estratégia de LLM. + + + ![Enterprise Testing Interface](/images/enterprise/enterprise-testing.png) + + +**Funcionalidades Avançadas de Teste:** + +- **Comparação Multi-Modelo**: Teste diversos LLMs simultaneamente nas mesmas tarefas e entradas. Compare desempenho entre GPT-4o, Claude, Llama, Groq, Cerebras, e outros líderes em paralelo para identificar a melhor opção para você. + +- **Rigor Estatístico**: Configure múltiplas iterações com inputs consistentes para medir confiabilidade e variação no desempenho. Assim, identifica modelos que performam bem e de modo consistente. + +- **Validação no Mundo Real**: Use os inputs e cenários reais da sua crew, e não apenas benchmarks sintéticos. A plataforma permite testar no contexto da sua indústria, empresa e casos de uso. + +- **Analytics Completo**: Acesse métricas detalhadas de desempenho, tempos de execução e análise de custos para todos os modelos testados. Decisões baseadas em dados reais, não apenas reputação. + +- **Colaboração em Equipe**: Compartilhe resultados e análises com seu time, favorecendo decisões coletivas e estratégias alinhadas. + +Acesse [app.crewai.com](https://app.crewai.com) para começar! + + +A plataforma Enterprise transforma a seleção de modelos de um "palpite" para um processo orientado por dados, permitindo validar os princípios deste guia com seus próprios casos de uso. + + +## Resumo dos Princípios-Chave + + + + Escolha os modelos pelo que sua tarefa realmente requer, não por reputação ou capacidades teóricas. + + + + Alinhe forças do modelo a papéis e responsabilidades dos agentes para melhor desempenho. + + + + Mantenha uma estratégia coerente de seleção de modelos em fluxos e componentes relacionados. + + + + Valide escolhas em uso real, não apenas em benchmarks. + + + + Comece simples e otimize com base na performance e necessidade práticas. + + + + Equilibre performance requerida, custo e complexidade. + + + + +Lembre-se: o melhor LLM é o que entrega consistentemente os resultados de que você precisa dentro de suas restrições. Conheça seu requisito primeiro, depois selecione o modelo mais adequado. + + +## Panorama Atual dos Modelos (Junho/2025) + + +**Retrato do Momento**: Os rankings a seguir representam o estado da arte em Junho de 2025, compilados do [LMSys Arena](https://arena.lmsys.org/), [Artificial Analysis](https://artificialanalysis.ai/) e outros benchmarks líderes. Performance, disponibilidade e preço mudam rapidamente. Sempre valide com seus dados e casos reais. + + +### Principais Modelos por Categoria + +As tabelas abaixo mostram uma amostra dos modelos de maior destaque em cada categoria, junto de orientação sobre aplicação em agentes CrewAI: + + +Estas tabelas exibem apenas alguns modelos líderes por categoria. Existem muitos outros excelentes. O objetivo é ilustrar exemplos de capacidades buscadas em vez de apresentar um catálogo completo. + + + + + **Melhores para LLMs Manager e Análises Complexas** + + | Modelo | Score de Inteligência | Custo ($/M tokens) | Velocidade | Melhor Uso em CrewAI | + |:------|:---------------------|:-------------------|:-----------|:--------------------| + | **o3** | 70 | $17.50 | Rápido | Manager LLM para coordenação multi-agente | + | **Gemini 2.5 Pro** | 69 | $3.44 | Rápido | Agentes de planejamento estratégico, coordenação de pesquisa | + | **DeepSeek R1** | 68 | $0.96 | Moderada | Raciocínio com bom custo-benefício | + | **Claude 4 Sonnet** | 53 | $6.00 | Rápido | Agentes de análise que precisam de nuance | + | **Qwen3 235B (Reasoning)** | 62 | $2.63 | Moderada | Alternativa open source para raciocínio | + + Esses modelos se destacam em raciocínio multi-etapas e são ideais para agentes que desenvolvem estratégias, coordenam outros agentes ou analisam informações complexas. + + + + **Melhores para Desenvolvimento e Workflows com Ferramentas** + + | Modelo | Performance em Coding | Tool Use Score | Custo ($/M tokens) | Melhor Uso em CrewAI | + |:--------|:---------------------|:--------------|:-------------------|:--------------------| + | **Claude 4 Sonnet** | Excelente | 72.7% | $6.00 | Agente principal de código/documentação técnica | + | **Claude 4 Opus** | Excelente | 72.5% | $30.00 | Arquitetura complexa, code review | + | **DeepSeek V3** | Muito bom | Alto | $0.48 | Coding econômico para desenvolvimentos rotineiros | + | **Qwen2.5 Coder 32B** | Muito bom | Médio | $0.15 | Agente de código econômico | + | **Llama 3.1 405B** | Bom | 81.1% | $3.50 | LLM para function calling em workflows intensivos em ferramentas | + + Otimizados para geração de código, debugging e solução técnica, ideais para equipes de desenvolvimento. + + + + **Melhores para Operações em Massa e Aplicações em Tempo Real** + + | Modelo | Velocidade (tokens/s) | Latência (TTFT) | Custo ($/M tokens) | Melhor Uso em CrewAI | + |:-------|:---------------------|:----------------|:-------------------|:---------------------| + | **Llama 4 Scout** | 2.600 | 0.33s | $0.27 | Agentes de processamento de alto volume | + | **Gemini 2.5 Flash** | 376 | 0.30s | $0.26 | Agentes de resposta em tempo real | + | **DeepSeek R1 Distill** | 383 | Variável | $0.04 | Processamento rápido de baixo custo | + | **Llama 3.3 70B** | 2.500 | 0.52s | $0.60 | Equilíbrio entre velocidade e capacidade | + | **Nova Micro** | Alto | 0.30s | $0.04 | Execução rápida de tarefas simples | + + Priorizam velocidade e eficiência, perfeitos para agentes em operações de rotina ou resposta ágil. **Dica:** Usar provedores de inference rápidos como Groq potencializa open source como Llama. + + + + **Melhores Modelos Coringa para Crews Diversos** + + | Modelo | Score Global | Versatilidade | Custo ($/M tokens) | Melhor Uso em CrewAI | + |:------------|:--------------|:-------------|:-------------------|:--------------------| + | **GPT-4.1** | 53 | Excelente | $3.50 | LLM generalista para equipes variadas | + | **Claude 3.7 Sonnet** | 48 | Muito boa | $6.00 | Raciocínio e criatividade balanceados | + | **Gemini 2.0 Flash** | 48 | Boa | $0.17 | Generalista de bom custo benefício | + | **Llama 4 Maverick** | 51 | Boa | $0.37 | Open source para usos gerais | + | **Qwen3 32B** | 44 | Boa | $1.23 | Versatilidade econômica | + + Oferecem bom desempenho geral, adequados para crews com demandas amplas. + + + +### Framework de Seleção para Modelos Atuais + + + + **Priorizando performance**: Use modelos topo de linha como **o3**, **Gemini 2.5 Pro** ou **Claude 4 Sonnet** para managers e agentes críticos. Excelentes em raciocínio e coordenação, porém mais caros. + + **Estratégia**: Implemente abordagem multi-modelo, reservando premium para raciocínio estratégico e eficientes para operações rotineiras. + + + + **Foco no orçamento**: Foque em modelos como **DeepSeek R1**, **Llama 4 Scout** ou **Gemini 2.0 Flash**, que trazem ótimo desempenho com investimento reduzido. + + **Estratégia**: Use modelos econômicos para maioria dos agentes, reservando premium apenas para funções críticas. + + + + **Para expertise específica**: Escolha modelos otimizados para seu principal caso de uso: **Claude 4** em código, **Gemini 2.5 Pro** em pesquisa, **Llama 405B** em function calling. + + **Estratégia**: Selecione conforme a principal função da crew, garantindo alinhamento de capacidade e modelo. + + + + **Para operações sensíveis**: Avalie modelos open source como **Llama 4** series, **DeepSeek V3** ou **Qwen3** para deployment privado, mantendo performance competitiva. + + **Estratégia**: Use open source em infraestrutura própria e aceite possíveis trade-offs por controle dos dados. + + + +### Considerações-Chave na Seleção de Modelos + +- **Tendências de Performance**: O cenário atual mostra competição forte entre modelos de raciocínio (o3, Gemini 2.5 Pro) e equilibrados (Claude 4, GPT-4.1). Modelos como DeepSeek R1 entregam excelente custo/performance. +- **Trade-off Velocidade x Inteligência**: Modelos como Llama 4 Scout priorizam velocidade (2.600 tokens/s) e inteligência razoável, enquanto outros como o3 maximizam raciocínio em detrimento de velocidade/preço. +- **Viabilidade Open Source**: A distância entre open source e proprietários diminui a cada mês, com Llama 4 Maverick e DeepSeek V3 entregando performance competitiva a preços atrativos. Inferência rápida via Groq maximiza custo-benefício nesses casos. + + +**Testes são essenciais**: Rankings servem de orientação geral, mas seu caso de uso, prompt e critério podem gerar resultados distintos. Sempre teste modelos candidatos com suas tarefas e dados reais antes de decidir. + + +### Estratégia Prática de Implementação + + + + Inicie com opções consagradas como **GPT-4.1**, **Claude 3.7 Sonnet** ou **Gemini 2.0 Flash**, que oferecem bom desempenho e ampla validação. + + + + Descubra se sua crew possui requisitos específicos (código, raciocínio, velocidade) que justifiquem modelos como **Claude 4 Sonnet** para desenvolvimento ou **o3** para análise. Para aplicações críticas em velocidade, considere Groq aliado à seleção do modelo. + + + + Use modelos diferentes para agentes distintos conforme o papel. Modelos de alta capacidade para managers e tarefas complexas, eficientes para rotinas. + + + + Acompanhe métricas relevantes ao seu caso e esteja pronto para ajustar modelos conforme lançamentos ou mudanças de preços. + + \ No newline at end of file diff --git a/docs/pt-BR/learn/multimodal-agents.mdx b/docs/pt-BR/learn/multimodal-agents.mdx new file mode 100644 index 000000000..a957753fd --- /dev/null +++ b/docs/pt-BR/learn/multimodal-agents.mdx @@ -0,0 +1,140 @@ +--- +title: Usando Agentes Multimodais +description: Aprenda como habilitar e usar capacidades multimodais em seus agentes para processar imagens e outros conteúdos não textuais dentro do framework CrewAI. +icon: video +--- + +## Usando Agentes Multimodais + +O CrewAI suporta agentes multimodais que podem processar tanto conteúdo textual quanto não textual, como imagens. Este guia mostrará como habilitar e utilizar capacidades multimodais em seus agentes. + +### Habilitando Capacidades Multimodais + +Para criar um agente multimodal, basta definir o parâmetro `multimodal` como `True` ao inicializar seu agente: + +```python +from crewai import Agent + +agent = Agent( + role="Image Analyst", + goal="Analyze and extract insights from images", + backstory="An expert in visual content interpretation with years of experience in image analysis", + multimodal=True # This enables multimodal capabilities +) +``` + +Ao definir `multimodal=True`, o agente é automaticamente configurado com as ferramentas necessárias para lidar com conteúdo não textual, incluindo a `AddImageTool`. + +### Trabalhando com Imagens + +O agente multimodal vem pré-configurado com a `AddImageTool`, permitindo que ele processe imagens. Não é necessário adicionar esta ferramenta manualmente – ela é automaticamente incluída ao habilitar capacidades multimodais. + +Aqui está um exemplo completo mostrando como usar um agente multimodal para analisar uma imagem: + +```python +from crewai import Agent, Task, Crew + +# Create a multimodal agent +image_analyst = Agent( + role="Product Analyst", + goal="Analyze product images and provide detailed descriptions", + backstory="Expert in visual product analysis with deep knowledge of design and features", + multimodal=True +) + +# Create a task for image analysis +task = Task( + description="Analyze the product image at https://example.com/product.jpg and provide a detailed description", + expected_output="A detailed description of the product image", + agent=image_analyst +) + +# Create and run the crew +crew = Crew( + agents=[image_analyst], + tasks=[task] +) + +result = crew.kickoff() +``` + +### Uso Avançado com Contexto + +Você pode fornecer contexto adicional ou perguntas específicas sobre a imagem ao criar tarefas para agentes multimodais. A descrição da tarefa pode incluir aspectos específicos nos quais você deseja que o agente foque: + +```python +from crewai import Agent, Task, Crew + +# Create a multimodal agent for detailed analysis +expert_analyst = Agent( + role="Visual Quality Inspector", + goal="Perform detailed quality analysis of product images", + backstory="Senior quality control expert with expertise in visual inspection", + multimodal=True # AddImageTool is automatically included +) + +# Create a task with specific analysis requirements +inspection_task = Task( + description=""" + Analyze the product image at https://example.com/product.jpg with focus on: + 1. Quality of materials + 2. Manufacturing defects + 3. Compliance with standards + Provide a detailed report highlighting any issues found. + """, + expected_output="A detailed report highlighting any issues found", + agent=expert_analyst +) + +# Create and run the crew +crew = Crew( + agents=[expert_analyst], + tasks=[inspection_task] +) + +result = crew.kickoff() +``` + +### Detalhes da Ferramenta + +Ao trabalhar com agentes multimodais, a `AddImageTool` é automaticamente configurada com o seguinte esquema: + +```python +class AddImageToolSchema: + image_url: str # Required: The URL or path of the image to process + action: Optional[str] = None # Optional: Additional context or specific questions about the image +``` + +O agente multimodal irá automaticamente realizar o processamento de imagens por meio de suas ferramentas internas, permitindo que ele: +- Acesse imagens via URLs ou caminhos de arquivos locais +- Processe o conteúdo da imagem com contexto opcional ou perguntas específicas +- Forneça análises e insights com base nas informações visuais e requisitos da tarefa + +### Boas Práticas + +Ao trabalhar com agentes multimodais, tenha em mente as seguintes boas práticas: + +1. **Acesso à Imagem** + - Certifique-se de que suas imagens estejam acessíveis via URLs alcançáveis pelo agente + - Para imagens locais, considere hospedá-las temporariamente ou utilize caminhos absolutos + - Verifique se as URLs das imagens são válidas e acessíveis antes de rodar as tarefas + +2. **Descrição da Tarefa** + - Seja específico sobre quais aspectos da imagem você deseja que o agente analise + - Inclua perguntas ou requisitos claros na descrição da tarefa + - Considere usar o parâmetro opcional `action` para uma análise focada + +3. **Gerenciamento de Recursos** + - O processamento de imagens pode exigir mais recursos computacionais do que tarefas apenas textuais + - Alguns modelos de linguagem podem exigir codificação em base64 para dados de imagem + - Considere o processamento em lote para múltiplas imagens visando otimizar o desempenho + +4. **Configuração do Ambiente** + - Verifique se seu ambiente possui as dependências necessárias para processamento de imagens + - Certifique-se de que seu modelo de linguagem suporta capacidades multimodais + - Teste primeiro com imagens pequenas para validar sua configuração + +5. **Tratamento de Erros** + - Implemente tratamento apropriado para falhas no carregamento de imagens + - Tenha estratégias de contingência para casos onde o processamento de imagens falhar + - Monitore e registre operações de processamento de imagens para depuração \ No newline at end of file diff --git a/docs/pt-BR/learn/overview.mdx b/docs/pt-BR/learn/overview.mdx new file mode 100644 index 000000000..70780db8a --- /dev/null +++ b/docs/pt-BR/learn/overview.mdx @@ -0,0 +1,158 @@ +--- +title: "Visão Geral" +description: "Aprenda como construir, personalizar e otimizar suas aplicações CrewAI com guias e tutoriais completos" +icon: "face-smile" +--- + +## Aprenda CrewAI + +Esta seção fornece guias e tutoriais completos para ajudar você a dominar o CrewAI, desde conceitos básicos até técnicas avançadas. Seja você iniciante ou esteja buscando otimizar suas implementações existentes, estes recursos o guiarão por todos os aspectos da construção de workflows poderosos de agentes de IA. + +## Guias de Introdução + +### Conceitos Centrais + + + Aprenda a executar tarefas em ordem sequencial para workflows estruturados. + + + + Implemente execução hierárquica de tarefas com agentes gerentes supervisionando workflows. + + + + Crie workflows dinâmicos com execução condicional de tarefas baseada em resultados. + + + + Execute crews de forma assíncrona para melhorar desempenho e concorrência. + + + +### Desenvolvimento de Agentes + + + Aprenda como personalizar o comportamento, funções e capacidades dos agentes. + + + + Construa agentes que podem escrever, executar e depurar código automaticamente. + + + + Crie agentes capazes de processar texto, imagens e outros tipos de mídia. + + + + Implemente agentes gerentes personalizados para workflows hierárquicos complexos. + + + +## Funcionalidades Avançadas + +### Controle de Workflow + + + Integre supervisão e intervenção humana aos workflows dos agentes. + + + + Permita entrada humana durante a execução de tarefas para tomada de decisões dinâmicas. + + + + Refaça e retome tarefas a partir de execuções anteriores de crews. + + + + Execute crews múltiplas vezes com diferentes entradas de maneira eficiente. + + + +### Personalização & Integração + + + Integre modelos de linguagem personalizados e provedores ao CrewAI. + + + + Configure e gerencie conexões com vários provedores de LLM. + + + + Construa ferramentas personalizadas para estender as capacidades dos agentes. + + + + Use anotações Python para um código mais limpo e fácil de manter. + + + +## Aplicações Especializadas + +### Conteúdo & Mídia + + + Gere imagens utilizando a integração DALL-E com seus agentes. + + + + Integre agentes e modelos já existentes aos workflows do CrewAI. + + + +### Gerenciamento de Ferramentas + + + Configure ferramentas para retornarem sua saída diretamente como resultado da tarefa. + + + +## Recomendações de Rotas de Aprendizagem + +### Para Iniciantes +1. Comece pelo **Processo Sequencial** para entender a execução básica de workflows +2. Aprenda **Personalizando Agentes** para criar configurações de agentes eficazes +3. Explore **Criar Ferramentas Personalizadas** para estender funcionalidades +4. Experimente **Humano no Loop** para workflows interativos + +### Para Usuários Intermediários +1. Domine **Processo Hierárquico** para sistemas multiagente complexos +2. Implemente **Tarefas Condicionais** para workflows dinâmicos +3. Utilize **Kickoff Assíncrono** para otimizar desempenho +4. Integre **LLM Personalizado** para modelos especializados + +### Para Usuários Avançados +1. Construa **Agentes Multimodais** para processamento complexo de mídias +2. Crie **Agentes Gerentes Personalizados** para orquestração sofisticada +3. Implemente **Traga Seu Próprio Agente** para sistemas híbridos +4. Use **Repetir Tarefas** para recuperação de erros robusta + +## Melhores Práticas + +### Desenvolvimento +- **Comece Simples**: Inicie com workflows sequenciais básicos antes de adicionar complexidade +- **Teste de Forma Incremental**: Teste cada componente antes de integrar em sistemas maiores +- **Use Anotações**: Aproveite as anotações Python para código mais limpo e sustentável +- **Ferramentas Personalizadas**: Crie ferramentas reutilizáveis que possam ser compartilhadas entre diferentes agentes + +### Produção +- **Tratamento de Erros**: Implemente mecanismos robustos de tratamento e recuperação de erros +- **Desempenho**: Utilize execução assíncrona e otimize chamadas a LLM para melhor desempenho +- **Monitoramento**: Integre ferramentas de observabilidade para acompanhar o desempenho dos agentes +- **Supervisão Humana**: Inclua checkpoints humanos para decisões críticas + +### Otimização +- **Gestão de Recursos**: Monitore e otimize o uso de tokens e custos de API +- **Design de Workflow**: Elabore workflows que minimizem chamadas desnecessárias ao LLM +- **Eficiência das Ferramentas**: Crie ferramentas eficientes que ofereçam máximo valor com o mínimo de overhead +- **Aprimoramento Iterativo**: Use feedback e métricas para melhorar continuamente o desempenho dos agentes + +## Obtendo Ajuda + +- **Documentação**: Cada guia inclui exemplos detalhados e explicações +- **Comunidade**: Participe do [Fórum CrewAI](https://community.crewai.com) para discussões e suporte +- **Exemplos**: Consulte a seção de Exemplos para implementações completas e funcionais +- **Suporte**: Entre em contato via [support@crewai.com](mailto:support@crewai.com) para assistência técnica + +Comece pelos guias que atendem às suas necessidades atuais e, gradualmente, explore tópicos mais avançados conforme você se sentir confortável com os fundamentos. diff --git a/docs/pt-BR/learn/replay-tasks-from-latest-crew-kickoff.mdx b/docs/pt-BR/learn/replay-tasks-from-latest-crew-kickoff.mdx new file mode 100644 index 000000000..18b6682b7 --- /dev/null +++ b/docs/pt-BR/learn/replay-tasks-from-latest-crew-kickoff.mdx @@ -0,0 +1,78 @@ +--- +title: Reexecutar Tarefas a partir do Último Crew Kickoff +description: Reexecute tarefas a partir do último crew.kickoff(...) +icon: arrow-right +--- + +## Introdução + +O CrewAI oferece a capacidade de reexecutar uma tarefa especificada a partir do último crew kickoff. Esse recurso é particularmente útil quando você concluiu um kickoff e deseja tentar novamente determinadas tarefas, ou não precisa buscar dados novamente porque seus agentes já possuem o contexto salvo da execução do kickoff, sendo necessário apenas reexecutar as tarefas desejadas. + + + Você deve executar `crew.kickoff()` antes de poder reexecutar uma tarefa. + Atualmente, apenas o kickoff mais recente é suportado, então se você utilizar `kickoff_for_each`, será possível reexecutar apenas a partir da execução de crew mais recente. + + +Aqui está um exemplo de como reexecutar a partir de uma tarefa: + +### Reexecutando a partir de uma Tarefa Específica Usando o CLI + +Para utilizar o recurso de reexecução, siga estes passos: + + + + + + Para visualizar os task_ids do último kickoff, utilize: + + ```shell + crewai log-tasks-outputs + ``` + + Após identificar o `task_id` que deseja reexecutar, utilize: + + ```shell + crewai replay -t + ``` + + + + + Certifique-se de que o `crewai` está instalado e devidamente configurado no seu ambiente de desenvolvimento. + + +### Reexecutando uma Tarefa Programaticamente + +Para reexecutar uma tarefa programaticamente, siga os passos abaixo: + + + + Especifique o `task_id` e os parâmetros de entrada para o processo de reexecução. + + + Execute o comando de reexecução dentro de um bloco try-except para lidar com possíveis erros. + + ```python Code + def replay(): + """ + Replay the crew execution from a specific task. + """ + task_id = '' + inputs = {"topic": "CrewAI Training"} # This is optional; you can pass in the inputs you want to replay; otherwise, it uses the previous kickoff's inputs. + try: + YourCrewName_Crew().crew().replay(task_id=task_id, inputs=inputs) + + except subprocess.CalledProcessError as e: + raise Exception(f"An error occurred while replaying the crew: {e}") + + except Exception as e: + raise Exception(f"An unexpected error occurred: {e}") + ``` + + + + +## Conclusão + +Com as melhorias acima e funcionalidades detalhadas, a reexecução de tarefas específicas no CrewAI ficou mais eficiente e robusta. +Certifique-se de seguir exatamente os comandos e passos para aproveitar ao máximo esses recursos. \ No newline at end of file diff --git a/docs/pt-BR/learn/sequential-process.mdx b/docs/pt-BR/learn/sequential-process.mdx new file mode 100644 index 000000000..2b3079feb --- /dev/null +++ b/docs/pt-BR/learn/sequential-process.mdx @@ -0,0 +1,127 @@ +--- +title: Processos Sequenciais +description: Um guia abrangente para utilizar os processos sequenciais na execução de tarefas em projetos CrewAI. +icon: forward +--- + +## Introdução + +O CrewAI oferece uma estrutura flexível para execução de tarefas de maneira estruturada, suportando tanto processos sequenciais quanto hierárquicos. +Este guia descreve como implementar esses processos de forma eficaz para garantir execução eficiente das tarefas e a conclusão do projeto. + +## Visão Geral do Processo Sequencial + +O processo sequencial garante que as tarefas sejam executadas uma após a outra, seguindo um progresso linear. +Essa abordagem é ideal para projetos nos quais as tarefas precisam ser concluídas em uma ordem específica. + +### Principais Características + +- **Fluxo Linear de Tarefas**: Garante o progresso ordenado ao tratar tarefas em uma sequência pré-determinada. +- **Simplicidade**: Melhor opção para projetos com tarefas claras e passo a passo. +- **Fácil Monitoramento**: Facilita o acompanhamento da conclusão das tarefas e do progresso do projeto. + +## Implementando o Processo Sequencial + +Para utilizar o processo sequencial, monte sua crew e defina as tarefas na ordem em que devem ser executadas. + +```python Code +from crewai import Crew, Process, Agent, Task, TaskOutput, CrewOutput + +# Define your agents +researcher = Agent( + role='Researcher', + goal='Conduct foundational research', + backstory='An experienced researcher with a passion for uncovering insights' +) +analyst = Agent( + role='Data Analyst', + goal='Analyze research findings', + backstory='A meticulous analyst with a knack for uncovering patterns' +) +writer = Agent( + role='Writer', + goal='Draft the final report', + backstory='A skilled writer with a talent for crafting compelling narratives' +) + +# Define your tasks +research_task = Task( + description='Gather relevant data...', + agent=researcher, + expected_output='Raw Data' +) +analysis_task = Task( + description='Analyze the data...', + agent=analyst, + expected_output='Data Insights' +) +writing_task = Task( + description='Compose the report...', + agent=writer, + expected_output='Final Report' +) + +# Form the crew with a sequential process +report_crew = Crew( + agents=[researcher, analyst, writer], + tasks=[research_task, analysis_task, writing_task], + process=Process.sequential +) + +# Execute the crew +result = report_crew.kickoff() + +# Accessing the type-safe output +task_output: TaskOutput = result.tasks[0].output +crew_output: CrewOutput = result.output +``` + +### Nota: + +Cada tarefa em um processo sequencial **deve** ter um agente atribuído. Certifique-se de que todo `Task` inclua um parâmetro `agent`. + +### Fluxo de Trabalho em Ação + +1. **Tarefa Inicial**: Em um processo sequencial, o primeiro agente conclui sua tarefa e sinaliza a finalização. +2. **Tarefas Subsequentes**: Os agentes assumem suas tarefas conforme o tipo de processo, com os resultados das tarefas anteriores ou diretrizes orientando sua execução. +3. **Finalização**: O processo é concluído assim que a última tarefa é executada, levando à conclusão do projeto. + +## Funcionalidades Avançadas + +### Delegação de Tarefas + +Em processos sequenciais, se um agente possui `allow_delegation` definido como `True`, ele pode delegar tarefas para outros agentes na crew. +Esse recurso é configurado automaticamente quando há múltiplos agentes na crew. + +### Execução Assíncrona + +As tarefas podem ser executadas de forma assíncrona, permitindo processamento paralelo quando apropriado. +Para criar uma tarefa assíncrona, defina `async_execution=True` ao criar a tarefa. + +### Memória e Cache + +O CrewAI suporta recursos de memória e cache: + +- **Memória**: Habilite definindo `memory=True` ao criar a Crew. Isso permite aos agentes reter informações entre as tarefas. +- **Cache**: Por padrão, o cache está habilitado. Defina `cache=False` para desativá-lo. + +### Callbacks + +Você pode definir callbacks tanto no nível da tarefa quanto no nível de etapa: + +- `task_callback`: Executado após a conclusão de cada tarefa. +- `step_callback`: Executado após cada etapa na execução de um agente. + +### Métricas de Uso + +O CrewAI rastreia o uso de tokens em todas as tarefas e agentes. Você pode acessar essas métricas após a execução. + +## Melhores Práticas para Processos Sequenciais + +1. **A Ordem Importa**: Organize as tarefas em uma sequência lógica, onde cada uma aproveite o resultado da anterior. +2. **Descrições Claras de Tarefas**: Forneça descrições detalhadas para cada tarefa, orientando os agentes de forma eficaz. +3. **Seleção Apropriada de Agentes**: Relacione as habilidades e funções dos agentes às necessidades de cada tarefa. +4. **Use o Contexto**: Aproveite o contexto das tarefas anteriores para informar as seguintes. + +Esta documentação atualizada garante que os detalhes reflitam com precisão as últimas mudanças no código e descreve claramente como aproveitar novos recursos e configurações. +O conteúdo foi mantido simples e direto para garantir fácil compreensão. \ No newline at end of file diff --git a/docs/pt-BR/learn/using-annotations.mdx b/docs/pt-BR/learn/using-annotations.mdx new file mode 100644 index 000000000..4aba63e17 --- /dev/null +++ b/docs/pt-BR/learn/using-annotations.mdx @@ -0,0 +1,141 @@ +--- +title: "Usando Anotações no crew.py" +description: "Aprenda como usar anotações para estruturar corretamente agentes, tarefas e componentes no CrewAI" +icon: "at" +--- + +Este guia explica como utilizar anotações para referenciar corretamente **agentes**, **tarefas** e outros componentes no arquivo `crew.py`. + +## Introdução + +As anotações no framework CrewAI são utilizadas para decorar classes e métodos, fornecendo metadados e funcionalidades para diversos componentes do seu crew. Essas anotações auxiliam na organização e estruturação do seu código, tornando-o mais legível e fácil de manter. + +## Anotações Disponíveis + +O framework CrewAI fornece as seguintes anotações: + +- `@CrewBase`: Usada para decorar a classe principal do crew. +- `@agent`: Decora métodos que definem e retornam objetos Agent. +- `@task`: Decora métodos que definem e retornam objetos Task. +- `@crew`: Decora o método que cria e retorna o objeto Crew. +- `@llm`: Decora métodos que inicializam e retornam objetos Language Model. +- `@tool`: Decora métodos que inicializam e retornam objetos Tool. +- `@callback`: Utilizada para definir métodos de callback. +- `@output_json`: Utilizada para métodos que retornam dados em JSON. +- `@output_pydantic`: Utilizada para métodos que retornam modelos Pydantic. +- `@cache_handler`: Utilizada para definição de métodos de manipulação de cache. + +## Exemplos de Uso + +Vamos passar por exemplos de como utilizar essas anotações: + +### 1. Classe Base do Crew + +```python +@CrewBase +class LinkedinProfileCrew(): + """LinkedinProfile crew""" + agents_config = 'config/agents.yaml' + tasks_config = 'config/tasks.yaml' +``` + +A anotação `@CrewBase` é usada para decorar a classe principal do crew. Esta classe geralmente contém as configurações e métodos para criação de agentes, tarefas e do próprio crew. + +### 2. Definição de Tool + +```python +@tool +def myLinkedInProfileTool(self): + return LinkedInProfileTool() +``` + +A anotação `@tool` é usada para decorar métodos que retornam objetos tool. Essas ferramentas podem ser usadas por agentes para executar tarefas específicas. + +### 3. Definição de LLM + +```python +@llm +def groq_llm(self): + api_key = os.getenv('api_key') + return ChatGroq(api_key=api_key, temperature=0, model_name="mixtral-8x7b-32768") +``` + +A anotação `@llm` é usada para decorar métodos que inicializam e retornam objetos Language Model. Esses LLMs são utilizados pelos agentes para tarefas de processamento de linguagem natural. + +### 4. Definição de Agente + +```python +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'] + ) +``` + +A anotação `@agent` é usada para decorar métodos que definem e retornam objetos Agent. + +### 5. Definição de Tarefa + +```python +@task +def research_task(self) -> Task: + return Task( + config=self.tasks_config['research_linkedin_task'], + agent=self.researcher() + ) +``` + +A anotação `@task` é usada para decorar métodos que definem e retornam objetos Task. Esses métodos especificam a configuração da tarefa e o agente responsável por ela. + +### 6. Criação do Crew + +```python +@crew +def crew(self) -> Crew: + """Creates the LinkedinProfile crew""" + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +A anotação `@crew` é usada para decorar o método que cria e retorna o objeto `Crew`. Este método reúne todos os componentes (agentes e tarefas) em um crew funcional. + +## Configuração YAML + +As configurações dos agentes geralmente são armazenadas em um arquivo YAML. Veja um exemplo de como o arquivo `agents.yaml` pode ser estruturado para o agente researcher: + +```yaml +researcher: + role: > + LinkedIn Profile Senior Data Researcher + goal: > + Uncover detailed LinkedIn profiles based on provided name {name} and domain {domain} + Generate a Dall-E image based on domain {domain} + backstory: > + You're a seasoned researcher with a knack for uncovering the most relevant LinkedIn profiles. + Known for your ability to navigate LinkedIn efficiently, you excel at gathering and presenting + professional information clearly and concisely. + allow_delegation: False + verbose: True + llm: groq_llm + tools: + - myLinkedInProfileTool + - mySerperDevTool + - myDallETool +``` + +Esta configuração YAML corresponde ao agente researcher definido na classe `LinkedinProfileCrew`. A configuração especifica o papel do agente, objetivo, contexto e outras propriedades, como o LLM e as tools que ele utiliza. + +Repare como os campos `llm` e `tools` no arquivo YAML correspondem aos métodos decorados com `@llm` e `@tool` na classe Python. + +## Boas Práticas + +- **Nomenclatura Consistente**: Utilize nomenclatura clara e consistente para seus métodos. Por exemplo, métodos de agentes podem ser nomeados de acordo com suas funções (ex: researcher, reporting_analyst). +- **Variáveis de Ambiente**: Utilize variáveis de ambiente para informações sensíveis como chaves de API. +- **Flexibilidade**: Estruture seu crew de forma flexível, permitindo fácil adição ou remoção de agentes e tarefas. +- **Correspondência YAML-Código**: Assegure que os nomes e estruturas nos arquivos YAML correspondam corretamente aos métodos decorados em seu código Python. + +Seguindo essas orientações e utilizando corretamente as anotações, você conseguirá criar crews bem estruturados e de fácil manutenção utilizando o framework CrewAI. \ No newline at end of file diff --git a/docs/pt-BR/mcp/multiple-servers.mdx b/docs/pt-BR/mcp/multiple-servers.mdx new file mode 100644 index 000000000..5044e19c7 --- /dev/null +++ b/docs/pt-BR/mcp/multiple-servers.mdx @@ -0,0 +1,64 @@ +--- +title: Conectando a Múltiplos Servidores MCP +description: Saiba como usar o MCPServerAdapter no CrewAI para conectar-se simultaneamente a múltiplos servidores MCP e agregar suas ferramentas. +icon: layer-group +--- + +## Visão Geral + +O `MCPServerAdapter` em `crewai-tools` permite que você conecte-se a vários servidores MCP simultaneamente. Isso é útil quando seus agentes precisam acessar ferramentas distribuídas entre diferentes serviços ou ambientes. O adaptador agrega as ferramentas de todos os servidores especificados, tornando-as disponíveis para seus agentes CrewAI. + +## Configuração + +Para conectar-se a múltiplos servidores, você fornece uma lista de dicionários de parâmetros de servidor para o `MCPServerAdapter`. Cada dicionário na lista deve definir os parâmetros para um servidor MCP. + +Os tipos de transporte suportados para cada servidor na lista incluem `stdio`, `sse` e `streamable-http`. + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters # Needed for Stdio example + +# Define parameters for multiple MCP servers +server_params_list = [ + # Streamable HTTP Server + { + "url": "http://localhost:8001/mcp", + "transport": "streamable-http" + }, + # SSE Server + { + "url": "http://localhost:8000/sse", + "transport": "sse" + }, + # StdIO Server + StdioServerParameters( + command="python3", + args=["servers/your_stdio_server.py"], + env={"UV_PYTHON": "3.12", **os.environ}, + ) +] + +try: + with MCPServerAdapter(server_params_list) as aggregated_tools: + print(f"Available aggregated tools: {[tool.name for tool in aggregated_tools]}") + + multi_server_agent = Agent( + role="Versatile Assistant", + goal="Utilize tools from local Stdio, remote SSE, and remote HTTP MCP servers.", + backstory="An AI agent capable of leveraging a diverse set of tools from multiple sources.", + tools=aggregated_tools, # All tools are available here + verbose=True, + ) + + ... # Your other agent, tasks, and crew code here + +except Exception as e: + print(f"Error connecting to or using multiple MCP servers (Managed): {e}") + print("Ensure all MCP servers are running and accessible with correct configurations.") + +``` + +## Gerenciamento de Conexão + +Ao utilizar o gerenciador de contexto (`with` statement), o `MCPServerAdapter` gerencia o ciclo de vida (início e término) de todas as conexões aos servidores MCP configurados. Isso simplifica o gerenciamento de recursos e garante que todas as conexões sejam devidamente fechadas ao sair do contexto. \ No newline at end of file diff --git a/docs/pt-BR/mcp/overview.mdx b/docs/pt-BR/mcp/overview.mdx new file mode 100644 index 000000000..dbdc0638d --- /dev/null +++ b/docs/pt-BR/mcp/overview.mdx @@ -0,0 +1,215 @@ +--- +title: 'Servidores MCP como Ferramentas no CrewAI' +description: 'Aprenda como integrar servidores MCP como ferramentas nos seus agentes CrewAI usando a biblioteca `crewai-tools`.' +icon: plug +--- + +## Visão Geral + +O [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) fornece uma maneira padronizada para agentes de IA fornecerem contexto para LLMs comunicando-se com serviços externos, conhecidos como Servidores MCP. +A biblioteca `crewai-tools` expande as capacidades do CrewAI permitindo que você integre facilmente ferramentas desses servidores MCP em seus agentes. +Isso oferece às suas crews acesso a um vasto ecossistema de funcionalidades. + +Atualmente, suportamos os seguintes mecanismos de transporte: + +- **Stdio**: para servidores locais (comunicação via entrada/saída padrão entre processos na mesma máquina) +- **Server-Sent Events (SSE)**: para servidores remotos (transmissão de dados unidirecional em tempo real do servidor para o cliente via HTTP) +- **Streamable HTTP**: para servidores remotos (comunicação flexível e potencialmente bidirecional via HTTP, geralmente utilizando SSE para streams do servidor para o cliente) + +## Tutorial em Vídeo +Assista a este tutorial em vídeo para um guia abrangente sobre a integração do MCP com o CrewAI: + + + +## Instalação + +Antes de começar a usar MCP com `crewai-tools`, é necessário instalar a dependência extra `mcp` do `crewai-tools` com o seguinte comando: + +```shell +uv pip install 'crewai-tools[mcp]' +``` + +## Conceitos Chave & Primeiros Passos + +A classe `MCPServerAdapter` da `crewai-tools` é a principal forma de conectar-se a um servidor MCP e disponibilizar suas ferramentas aos seus agentes CrewAI. Ela suporta diferentes mecanismos de transporte e simplifica o gerenciamento de conexões. + +O uso de um gerenciador de contexto Python (`with`) é a **abordagem recomendada** para o `MCPServerAdapter`. Ele lida automaticamente com a abertura e o fechamento da conexão com o servidor MCP. + +```python +from crewai import Agent +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters # Para servidor Stdio + +# Exemplo de server_params (escolha um baseado no seu tipo de servidor): +# 1. Servidor Stdio: +server_params=StdioServerParameters( + command="python3", + args=["servers/your_server.py"], + env={"UV_PYTHON": "3.12", **os.environ}, +) + +# 2. Servidor SSE: +server_params = { + "url": "http://localhost:8000/sse", + "transport": "sse" +} + +# 3. Servidor Streamable HTTP: +server_params = { + "url": "http://localhost:8001/mcp", + "transport": "streamable-http" +} + +# Exemplo de uso (descomente e adapte após definir server_params): +with MCPServerAdapter(server_params) as mcp_tools: + print(f"Available tools: {[tool.name for tool in mcp_tools]}") + + my_agent = Agent( + role="MCP Tool User", + goal="Utilize tools from an MCP server.", + backstory="I can connect to MCP servers and use their tools.", + tools=mcp_tools, # Passe as ferramentas carregadas para o seu agente + reasoning=True, + verbose=True + ) + # ... restante da configuração do seu crew ... +``` +Este padrão geral mostra como integrar ferramentas. Para exemplos específicos para cada transporte, consulte os guias detalhados abaixo. + +## Filtrando Ferramentas + +```python +with MCPServerAdapter(server_params) as mcp_tools: + print(f"Available tools: {[tool.name for tool in mcp_tools]}") + + my_agent = Agent( + role="MCP Tool User", + goal="Utilize tools from an MCP server.", + backstory="I can connect to MCP servers and use their tools.", + tools=mcp_tools["tool_name"], # Passe as ferramentas filtradas para o seu agente + reasoning=True, + verbose=True + ) + # ... restante da configuração do seu crew ... +``` + +## Usando com CrewBase + +Para usar ferramentas de servidores MCP dentro de uma classe CrewBase, utilize o método `mcp_tools`. As configurações dos servidores devem ser fornecidas via o atributo mcp_server_params. Você pode passar uma configuração única ou uma lista com múltiplas configurações. + +```python +@CrewBase +class CrewWithMCP: + # ... defina o arquivo de configuração de agentes e tasks ... + + mcp_server_params = [ + # Servidor Streamable HTTP + { + "url": "http://localhost:8001/mcp", + "transport": "streamable-http" + }, + # Servidor SSE + { + "url": "http://localhost:8000/sse", + "transport": "sse" + }, + # Servidor StdIO + StdioServerParameters( + command="python3", + args=["servers/your_stdio_server.py"], + env={"UV_PYTHON": "3.12", **os.environ}, + ) + ] + + @agent + def your_agent(self): + return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) # você também pode filtrar quais ferramentas estarão disponíveis + + # ... restante da configuração do seu crew ... +``` +## Explore Integrações MCP + + + + Conecte-se a servidores MCP locais via entrada/saída padrão. Ideal para scripts e executáveis locais. + + + Integre com servidores MCP remotos usando Server-Sent Events para streaming de dados em tempo real. + + + Utilize HTTP Streamable para uma comunicação robusta com servidores MCP remotos. + + + Agregue ferramentas de vários servidores MCP simultaneamente usando um único adaptador. + + + Revise práticas importantes de segurança para integração MCP e mantenha seus agentes protegidos. + + + +Confira este repositório para demonstrações completas e exemplos de integração MCP com CrewAI! 👇 + + +Demo MCP do CrewAI + + +## Segurança ao Usar MCP + +Sempre assegure-se de confiar no servidor MCP antes de utilizá-lo. + + +#### Aviso de Segurança: Ataques de DNS Rebinding +Transportes SSE podem ser vulneráveis a ataques de DNS rebinding se não forem devidamente protegidos. +Para prevenir isso: + +1. **Sempre valide os cabeçalhos Origin** das conexões SSE recebidas para garantir que venham de fontes esperadas +2. **Evite vincular servidores a todas as interfaces de rede** (0.0.0.0) quando executando localmente – faça o bind apenas para localhost (127.0.0.1) +3. **Implemente autenticação adequada** para todas as conexões SSE + +Sem essas proteções, invasores podem usar DNS rebinding para interagir com servidores MCP locais via sites remotos. + +Para mais detalhes, consulte a [documentação de Segurança de Transporte da MCP da Anthropic](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations). + +### Limitações +* **Primitivas Suportadas**: Atualmente, o `MCPServerAdapter` suporta principalmente a adaptação de `tools` MCP. +Outras primitivas MCP como `prompts` ou `resources` não são integradas diretamente como componentes CrewAI através deste adaptador por enquanto. +* **Manipulação de Saída**: O adaptador normalmente processa a saída principal de texto de uma ferramenta MCP (por exemplo, `.content[0].text`). Saídas complexas ou multimodais podem exigir tratamento customizado caso não se encaixem nesse padrão. diff --git a/docs/pt-BR/mcp/security.mdx b/docs/pt-BR/mcp/security.mdx new file mode 100644 index 000000000..6c68c31c3 --- /dev/null +++ b/docs/pt-BR/mcp/security.mdx @@ -0,0 +1,165 @@ +--- +title: Considerações de Segurança MCP +description: Saiba mais sobre as principais melhores práticas de segurança ao integrar servidores MCP com seus agentes CrewAI. +icon: lock +--- + +## Visão Geral + + +O aspecto mais crítico da segurança MCP é a **confiança**. Você deve **apenas** conectar seus agentes CrewAI a servidores MCP nos quais confie plenamente. + + +Ao integrar serviços externos como servidores MCP (Model Context Protocol) aos seus agentes CrewAI, a segurança é fundamental. +Servidores MCP podem executar código, acessar dados ou interagir com outros sistemas com base nas ferramentas que expõem. +É crucial compreender as implicações e seguir as melhores práticas para proteger suas aplicações e dados. + +### Riscos + +- Executar código arbitrário na máquina onde o agente está rodando (especialmente com o transporte `Stdio` se o servidor puder controlar o comando executado). +- Expor dados sensíveis do seu agente ou do seu ambiente. +- Manipular o comportamento do seu agente de maneiras não intencionais, incluindo realizar chamadas de API não autorizadas em seu nome. +- Sequestrar o processo de raciocínio do agente através de técnicas sofisticadas de prompt injection (veja abaixo). + +### 1. Confiando em Servidores MCP + + +**Somente conecte-se a servidores MCP em que confie.** + + +Antes de configurar o `MCPServerAdapter` para conectar a um servidor MCP, certifique-se de saber: +- **Quem opera o servidor?** É um serviço conhecido, de reputação confiável, ou um servidor interno sob o seu controle? +- **Quais ferramentas ele expõe?** Entenda as capacidades das ferramentas. Elas poderiam ser mal utilizadas caso um invasor obtenha controle ou se o próprio servidor for malicioso? +- **Quais dados ele acessa ou processa?** Saiba se há informações sensíveis que possam ser enviadas ou manipuladas pelo servidor MCP. + +Evite conectar-se a servidores MCP desconhecidos ou não verificados, especialmente se seus agentes lidam com tarefas ou dados sensíveis. + +### 2. Prompt Injection Seguro via Metadados de Ferramentas: O Risco do "Model Control Protocol" + +Um risco significativo e sutil é o potencial para prompt injection através dos metadados das ferramentas. Veja como funciona: + +1. Quando seu agente CrewAI se conecta a um servidor MCP, ele normalmente solicita uma lista de ferramentas disponíveis. +2. O servidor MCP responde com metadados para cada ferramenta, incluindo nome, descrição e descrições de parâmetros. +3. O LLM (Modelo de Linguagem) subjacente do seu agente usa esses metadados para entender como e quando usar as ferramentas. Muitas vezes esses metadados são incorporados no system prompt ou contexto do LLM. +4. Um servidor MCP malicioso pode construir seus metadados (nomes, descrições) para incluir instruções ocultas ou explícitas. Essas instruções podem atuar como prompt injection, efetivamente fazendo o LLM se comportar de determinada maneira, revelar informações sensíveis ou executar ações maliciosas. + +**Crucialmente, esse ataque pode ocorrer simplesmente ao conectar-se a um servidor malicioso e listar suas ferramentas, mesmo que seu agente nunca decida *usar* essas ferramentas.** A mera exposição aos metadados maliciosos pode ser suficiente para comprometer o comportamento do agente. + +**Mitigação:** + +* **Extrema Cautela com Servidores Não Confiáveis:** Reitere: *Não conecte-se a servidores MCP nos quais você não confie totalmente.* O risco de injection de metadados torna isso fundamental. + +### Segurança do Transporte Stdio + +O transporte Stdio (Entrada/Saída Padrão) é tipicamente usado para servidores MCP locais, rodando na mesma máquina que sua aplicação CrewAI. + +- **Isolamento de Processo**: Embora geralmente seja mais seguro pois não envolve exposição de rede por padrão, assegure-se de que o script ou comando executado pelo `StdioServerParameters` é de uma fonte confiável e possui permissões de sistema de arquivos adequadas. Um script Stdio servidor malicioso pode ainda prejudicar seu sistema local. +- **Saneamento de Entrada**: Se o seu script de servidor Stdio recebe entradas complexas derivadas das interações do agente, garanta que o script saneie essas entradas para evitar injection de comandos ou outras vulnerabilidades na lógica do script. +- **Limite de Recursos**: Esteja atento ao fato de que o processo servidor Stdio consome recursos locais (CPU, memória). Assegure-se de que seja bem comportado, evitando esgotar os recursos do sistema. + +### Ataques de Confused Deputy + +O [Problema do Confused Deputy](https://en.wikipedia.org/wiki/Confused_deputy_problem) é uma vulnerabilidade clássica de segurança que pode se manifestar em integrações MCP, especialmente quando um servidor MCP atua como proxy para outros serviços de terceiros (ex: Google Calendar, GitHub) que usam OAuth 2.0 para autorização. + +**Cenário:** + +1. Um servidor MCP (vamos chamá-lo de `MCP-Proxy`) permite que seu agente interaja com o `ThirdPartyAPI`. +2. O `MCP-Proxy` usa seu próprio `client_id` estático ao comunicar-se com o servidor de autorização do `ThirdPartyAPI`. +3. Você, como usuário, autoriza legitimamente o `MCP-Proxy` a acessar o `ThirdPartyAPI` em seu nome. Durante esse processo, o servidor de autenticação pode definir um cookie no seu navegador indicando seu consentimento para o `client_id` do `MCP-Proxy`. +4. Um invasor cria um link malicioso. Esse link inicia um fluxo OAuth com o `MCP-Proxy`, mas é projetado para enganar o servidor de autenticação do `ThirdPartyAPI`. +5. Se você clicar nesse link e o servidor de autenticação do `ThirdPartyAPI` encontrar seu cookie de consentimento existente para o `client_id` do `MCP-Proxy`, pode *deixar de* pedir seu consentimento novamente. +6. O `MCP-Proxy` pode, então, ser enganado a encaminhar um código de autorização (para o `ThirdPartyAPI`) para o atacante, ou um código de autorização MCP que o atacante possa usar para se passar por você perante o `MCP-Proxy`. + +**Mitigação (Principalmente para Desenvolvedores de Servidores MCP):** + +* Servidores proxy MCP usando IDs de cliente estáticos para serviços downstream **devem** obter consentimento explícito do usuário para *cada aplicação cliente ou agente* conectando-se a eles *antes* de iniciar um fluxo OAuth com o serviço de terceiros. Isso significa que o `MCP-Proxy` deve exibir uma tela de consentimento. + +**Implicação para Usuários CrewAI:** + +* Fique atento se um servidor MCP redireciona você para múltiplas autenticações OAuth, especialmente se isso for inesperado ou se as permissões solicitadas forem muito amplas. +* Prefira servidores MCP que deixem clara sua própria identidade e a identidade dos serviços de terceiros que possam fazer proxy. + +### Segurança no Transporte Remoto (SSE & HTTP Transmitível) + +Ao conectar-se a servidores MCP remotos via Server-Sent Events (SSE) ou HTTP transmitível, práticas padrão de segurança web são essenciais. + +### Considerações de Segurança SSE + +### a. Ataques de DNS Rebinding (Especialmente para SSE) + + +**Proteja-se contra ataques de DNS Rebinding.** + + +DNS rebinding permite que um site controlado por atacante contorne a política de mesma origem e faça requisições para servidores na rede local do usuário (ex: `localhost`) ou intranet. Isso é particularmente arriscado se você roda um servidor MCP localmente (ex: para desenvolvimento) e um agente em um ambiente do tipo navegador (embora menos comum no backend CrewAI) ou se o servidor MCP está em uma rede interna. + +**Estratégias de Mitigação para Implementadores de Servidores MCP:** +- **Valide os Headers `Origin` e `Host`**: Servidores MCP (especialmente com SSE) devem validar os headers HTTP `Origin` e/ou `Host` para garantir que as requisições venham dos domínios/clientes esperados. +- **Ligue em `localhost` (127.0.0.1)**: Ao rodar servidores MCP localmente para desenvolvimento, conecte-se a `127.0.0.1` em vez de `0.0.0.0`. Isso impede que sejam acessíveis por outras máquinas na rede. +- **Autenticação**: Exija autenticação para todas as conexões ao seu servidor MCP caso não seja destinado a acesso público anônimo. + +### b. Use HTTPS + +- **Criptografe Dados em Trânsito**: Sempre use HTTPS (HTTP Seguro) para URLs de servidores MCP remotos. Isso criptografa a comunicação entre sua aplicação CrewAI e o servidor MCP, protegendo contra escuta e ataques Man-in-the-Middle (MitM). O `MCPServerAdapter` respeitará o esquema (`http` ou `https`) fornecido na URL. + +### c. Token Passthrough (Anti-Padrão) + +Isso é uma preocupação principalmente para desenvolvedores de servidores MCP, mas entender o conceito ajuda a escolher servidores seguros. + +"Token passthrough" é quando um servidor MCP aceita um token de acesso do seu agente CrewAI (que pode ser um token para um serviço *diferente*, por exemplo, `ServiceA`) e simplesmente o repassa para outra API ( `ServiceB`) downstream sem validação adequada. Especificamente, `ServiceB` (ou o próprio servidor MCP) só deveria aceitar tokens explicitamente emitidos *para eles* (ou seja, o claim 'audience' no token deve corresponder ao servidor/serviço). + +**Riscos:** + +* Burlar controles de segurança (como limites de taxa ou permissões granulares) no servidor MCP ou na API downstream. +* Quebra trilhas de auditoria e responsabilização. +* Permite uso indevido de tokens roubados. + +**Mitigação (Para Desenvolvedores de Servidores MCP):** + +* Servidores MCP **NÃO DEVEM** aceitar tokens que não foram explicitamente emitidos para eles. Devem validar o claim de audiência dos tokens. + +**Implicação para Usuários CrewAI:** + +* Embora isso não seja diretamente controlável pelo usuário, destaca a importância de conectar-se a servidores MCP bem projetados e que sigam as melhores práticas de segurança. + +#### Autenticação e Autorização + +- **Verifique a Identidade**: Se o servidor MCP fornece ferramentas sensíveis ou acesso a dados privados, ele DEVE implementar mecanismos de autenticação robustos para verificar a identidade do cliente (sua aplicação CrewAI). Isso pode envolver chaves de API, tokens OAuth ou outros métodos padrão. +- **Princípio do Menor Privilégio**: Certifique-se de que as credenciais usadas pelo `MCPServerAdapter` (se houver) tenham apenas as permissões necessárias para acessar as ferramentas requeridas. + +### d. Validação e Saneamento de Entrada + +- **Validação de Entrada é Crítica**: Servidores MCP **devem** validar rigorosamente todas as entradas recebidas de agentes *antes* de processá-las ou passá-las para as ferramentas. Esta é a principal defesa contra diversas vulnerabilidades comuns: + - **Injection de Comando:** Caso uma ferramenta construa comandos de shell, queries SQL ou outras instruções de linguagens interpretadas a partir da entrada, o servidor deve sanitizar cuidadosamente esta entrada para evitar que comandos maliciosos sejam injetados e executados. + - **Path Traversal:** Se uma ferramenta acessa arquivos com base em parâmetros de entrada, o servidor deve validar e sanitizar esses caminhos para evitar acesso a arquivos ou diretórios não autorizados (por exemplo, bloqueando sequências `../`). + - **Verificações de Tipo e Faixa de Dados:** Servidores devem garantir que os dados de entrada estejam nos tipos esperados (ex: string, número, booleano) e dentro de faixas aceitáveis ou em formatos definidos (ex: regex para URLs). + - **Validação de Schema JSON:** Todos os parâmetros das ferramentas devem ser validados estritamente com seus esquemas JSON definidos. Isso ajuda a capturar requisições mal formatadas precocemente. +- **Atenção do Lado do Cliente**: Embora a validação no servidor seja fundamental, como usuário CrewAI, fique atento aos dados que seus agentes são configurados para enviar a ferramentas MCP, especialmente ao interagir com servidores MCP novos ou menos confiáveis. + +### e. Limite de Taxa e Gerenciamento de Recursos + +- **Previna Abusos**: Servidores MCP devem implementar limite de taxa para prevenir abusos, seja intencional (ataques de negação de serviço) ou não intencional (ex: um agente mal configurado fazendo muitas requisições). +- **Re-tentativas do Lado do Cliente**: Implemente lógica de repetição sensata em suas tarefas CrewAI se problemas de rede transitórios ou limites de taxa do servidor forem esperados, mas evite re-tentativas agressivas que possam aumentar a carga do servidor. + +## 4. Conselhos para Implementação de Servidor MCP Seguro (Para Desenvolvedores) + +Se você está desenvolvendo um servidor MCP ao qual agentes CrewAI possam se conectar, considere estas melhores práticas além dos pontos acima: + +- **Siga Práticas de Código Seguro**: Adote princípios padrão de programação segura para sua linguagem e framework escolhidos (ex: OWASP Top 10). +- **Princípio do Menor Privilégio**: Certifique-se de que o processo que executa o servidor MCP (especialmente para `Stdio`) tenha apenas as permissões mínimas necessárias. As próprias ferramentas também devem operar com o mínimo de privilégio necessário para executar sua função. +- **Gerenciamento de Dependências**: Mantenha todas as dependências do lado do servidor, incluindo pacotes do sistema operacional, runtimes de linguagem e bibliotecas de terceiros, sempre atualizadas para corrigir vulnerabilidades conhecidas. Use ferramentas para escanear por dependências vulneráveis. +- **Padrões Seguros por Padrão**: Projete seu servidor e suas ferramentas para serem seguros por padrão. Por exemplo, recursos potencialmente arriscados devem ser desabilitados por padrão ou requerer ativação explícita, com avisos claros. +- **Controle de Acesso para Ferramentas**: Implemente mecanismos robustos para controlar quais agentes ou usuários autenticados e autorizados podem acessar ferramentas específicas, especialmente as que são poderosas, sensíveis ou incorram em custos. +- **Tratamento Seguro de Erros**: Servidores não devem expor mensagens detalhadas de erro interno, traces de stack ou informações de debug para o cliente, pois estas podem revelar detalhes internos ou potenciais vulnerabilidades. Logue os erros de forma abrangente no lado do servidor para diagnóstico. +- **Log e Monitoramento Abrangentes**: Implemente um log detalhado de eventos relevantes para segurança (ex: tentativas de autenticação, invocações de ferramenta, erros, mudanças de autorização). Monitore esses logs em busca de atividades suspeitas ou padrões de abuso. +- **Aderência à Especificação de Autorização MCP**: Caso implemente autenticação e autorização, siga estritamente a [especificação de autorização MCP](https://modelcontextprotocol.io/specification/draft/basic/authorization) e as [melhores práticas de segurança OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc9700) relevantes. +- **Auditorias de Segurança Regulares**: Caso seu servidor MCP manipule dados sensíveis, realize operações críticas ou seja exposto publicamente, considere auditorias de segurança periódicas conduzidas por profissionais qualificados. + +## 5. Leituras Adicionais + +Para informações mais detalhadas sobre segurança MCP, consulte a documentação oficial: +- **[Segurança de Transporte MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations)** + +Ao entender essas considerações de segurança e implementar as melhores práticas, você pode aproveitar com segurança o poder dos servidores MCP em seus projetos CrewAI. +Estes pontos não esgotam o assunto, mas cobrem as questões de segurança mais comuns e críticas. +As ameaças continuarão a evoluir, por isso é importante se manter informado e adaptar suas medidas de segurança de acordo. \ No newline at end of file diff --git a/docs/pt-BR/mcp/sse.mdx b/docs/pt-BR/mcp/sse.mdx new file mode 100644 index 000000000..380a346e0 --- /dev/null +++ b/docs/pt-BR/mcp/sse.mdx @@ -0,0 +1,150 @@ +--- +title: Transporte SSE +description: Saiba como conectar o CrewAI a servidores MCP remotos usando Server-Sent Events (SSE) para comunicação em tempo real. +icon: wifi +--- + +## Visão Geral + +Server-Sent Events (SSE) fornecem uma forma padrão para um servidor web enviar atualizações a um cliente através de uma única conexão HTTP de longa duração. No contexto do MCP, SSE é utilizado para que servidores remotos transmitam dados (como respostas de ferramentas) para sua aplicação CrewAI em tempo real. + +## Conceitos-Chave + +- **Servidores Remotos**: SSE é adequado para servidores MCP hospedados remotamente. +- **Fluxo Unidirecional**: Normalmente, SSE é um canal de comunicação de mão única, do servidor para o cliente. +- **Configuração do `MCPServerAdapter`**: Para SSE, você fornecerá a URL do servidor e especificará o tipo de transporte. + +## Conectando via SSE + +Você pode se conectar a um servidor MCP baseado em SSE usando duas abordagens principais para gerenciar o ciclo de vida da conexão: + +### 1. Conexão Totalmente Gerenciada (Recomendado) + +Utilizar um gerenciador de contexto Python (`with` statement) é a abordagem recomendada. Ele lida automaticamente com o estabelecimento e o encerramento da conexão com o servidor MCP SSE. + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter + +server_params = { + "url": "http://localhost:8000/sse", # Replace with your actual SSE server URL + "transport": "sse" +} + +# Using MCPServerAdapter with a context manager +try: + with MCPServerAdapter(server_params) as tools: + print(f"Available tools from SSE MCP server: {[tool.name for tool in tools]}") + + # Example: Using a tool from the SSE MCP server + sse_agent = Agent( + role="Remote Service User", + goal="Utilize a tool provided by a remote SSE MCP server.", + backstory="An AI agent that connects to external services via SSE.", + tools=tools, + reasoning=True, + verbose=True, + ) + + sse_task = Task( + description="Fetch real-time stock updates for 'AAPL' using an SSE tool.", + expected_output="The latest stock price for AAPL.", + agent=sse_agent, + markdown=True + ) + + sse_crew = Crew( + agents=[sse_agent], + tasks=[sse_task], + verbose=True, + process=Process.sequential + ) + + if tools: # Only kickoff if tools were loaded + result = sse_crew.kickoff() # Add inputs={'stock_symbol': 'AAPL'} if tool requires it + print("\nCrew Task Result (SSE - Managed):\n", result) + else: + print("Skipping crew kickoff as tools were not loaded (check server connection).") + +except Exception as e: + print(f"Error connecting to or using SSE MCP server (Managed): {e}") + print("Ensure the SSE MCP server is running and accessible at the specified URL.") + +``` + + +Substitua `"http://localhost:8000/sse"` pela URL real do seu servidor MCP SSE. + + +### 2. Ciclo de Vida Manual da Conexão + +Caso precise de um controle mais detalhado, você pode gerenciar manualmente o ciclo de vida da conexão do `MCPServerAdapter`. + + +Você **DEVE** chamar `mcp_server_adapter.stop()` para garantir que a conexão seja encerrada e os recursos liberados. O uso de um bloco `try...finally` é altamente recomendado. + + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter + +server_params = { + "url": "http://localhost:8000/sse", # Replace with your actual SSE server URL + "transport": "sse" +} + +mcp_server_adapter = None +try: + mcp_server_adapter = MCPServerAdapter(server_params) + mcp_server_adapter.start() + tools = mcp_server_adapter.tools + print(f"Available tools (manual SSE): {[tool.name for tool in tools]}") + + manual_sse_agent = Agent( + role="Remote Data Analyst", + goal="Analyze data fetched from a remote SSE MCP server using manual connection management.", + backstory="An AI skilled in handling SSE connections explicitly.", + tools=tools, + verbose=True + ) + + analysis_task = Task( + description="Fetch and analyze the latest user activity trends from the SSE server.", + expected_output="A summary report of user activity trends.", + agent=manual_sse_agent + ) + + analysis_crew = Crew( + agents=[manual_sse_agent], + tasks=[analysis_task], + verbose=True, + process=Process.sequential + ) + + result = analysis_crew.kickoff() + print("\nCrew Task Result (SSE - Manual):\n", result) + +except Exception as e: + print(f"An error occurred during manual SSE MCP integration: {e}") + print("Ensure the SSE MCP server is running and accessible.") +finally: + if mcp_server_adapter and mcp_server_adapter.is_connected: + print("Stopping SSE MCP server connection (manual)...") + mcp_server_adapter.stop() # **Crucial: Ensure stop is called** + elif mcp_server_adapter: + print("SSE MCP server adapter was not connected. No stop needed or start failed.") + +``` + +## Considerações de Segurança para SSE + + +**Ataques de DNS Rebinding**: Transportes SSE podem ser vulneráveis a ataques de DNS rebinding se o servidor MCP não estiver devidamente protegido. Isso pode permitir que sites maliciosos interajam com servidores MCP locais ou da intranet. + + +Para mitigar esse risco: +- As implementações do servidor MCP devem **validar os cabeçalhos `Origin`** em conexões SSE recebidas. +- Ao rodar servidores MCP SSE locais para desenvolvimento, **faça o bind apenas em `localhost` (`127.0.0.1`)** ao invés de todas as interfaces de rede (`0.0.0.0`). +- Implemente **autenticação adequada** para todas as conexões SSE caso exponham ferramentas ou dados sensíveis. + +Para uma visão abrangente das melhores práticas de segurança, consulte nossa página de [Considerações de Segurança](./security.mdx) e a documentação oficial [MCP Transport Security](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations). \ No newline at end of file diff --git a/docs/pt-BR/mcp/stdio.mdx b/docs/pt-BR/mcp/stdio.mdx new file mode 100644 index 000000000..e256c11f6 --- /dev/null +++ b/docs/pt-BR/mcp/stdio.mdx @@ -0,0 +1,133 @@ +--- +title: Transporte Stdio +description: Aprenda como conectar o CrewAI a servidores MCP locais usando o mecanismo de transporte Stdio (Entrada/Saída Padrão). +icon: server +--- + +## Visão Geral + +O transporte Stdio (Entrada/Saída Padrão) é projetado para conectar o `MCPServerAdapter` a servidores MCP locais que se comunicam por meio de seus fluxos de entrada e saída padrão. Isso é normalmente utilizado quando o servidor MCP é um script ou executável rodando na mesma máquina da sua aplicação CrewAI. + +## Conceitos-Chave + +- **Execução Local**: O transporte Stdio gerencia um processo localmente em execução para o servidor MCP. +- **`StdioServerParameters`**: Esta classe da biblioteca `mcp` é usada para configurar o comando, argumentos e variáveis de ambiente para iniciar o servidor Stdio. + +## Conectando via Stdio + +Você pode se conectar a um servidor MCP baseado em Stdio usando duas abordagens principais para gerenciar o ciclo de vida da conexão: + +### 1. Conexão Totalmente Gerenciada (Recomendado) + +Usar um context manager do Python (declaração `with`) é a abordagem recomendada. Ela lida automaticamente com o início do processo do servidor MCP e sua finalização quando o contexto é encerrado. + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters +import os + +# Criar um objeto StdioServerParameters +server_params=StdioServerParameters( + command="python3", + args=["servers/your_stdio_server.py"], + env={"UV_PYTHON": "3.12", **os.environ}, +) + +with MCPServerAdapter(server_params) as tools: + print(f"Available tools from Stdio MCP server: {[tool.name for tool in tools]}") + + # Exemplo: Usando as ferramentas do servidor MCP Stdio em um Agente CrewAI + research_agent = Agent( + role="Local Data Processor", + goal="Process data using a local Stdio-based tool.", + backstory="An AI that leverages local scripts via MCP for specialized tasks.", + tools=tools, + reasoning=True, + verbose=True, + ) + + processing_task = Task( + description="Process the input data file 'data.txt' and summarize its contents.", + expected_output="A summary of the processed data.", + agent=research_agent, + markdown=True + ) + + data_crew = Crew( + agents=[research_agent], + tasks=[processing_task], + verbose=True, + process=Process.sequential + ) + + result = data_crew.kickoff() + print("\nCrew Task Result (Stdio - Managed):\n", result) + +``` + +### 2. Ciclo de Vida Manual da Conexão + +Se você precisa de um controle mais refinado sobre quando o processo do servidor MCP Stdio é iniciado e finalizado, pode gerenciar o ciclo de vida do `MCPServerAdapter` manualmente. + + +Você **DEVE** chamar `mcp_server_adapter.stop()` para garantir que o processo do servidor seja finalizado e os recursos, liberados. Recomenda-se fortemente o uso de um bloco `try...finally`. + + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters +import os + +# Criar um objeto StdioServerParameters +stdio_params=StdioServerParameters( + command="python3", + args=["servers/your_stdio_server.py"], + env={"UV_PYTHON": "3.12", **os.environ}, +) + +mcp_server_adapter = MCPServerAdapter(server_params=stdio_params) +try: + mcp_server_adapter.start() # Inicia manualmente a conexão e o processo do servidor + tools = mcp_server_adapter.tools + print(f"Available tools (manual Stdio): {[tool.name for tool in tools]}") + + # Exemplo: Usando as ferramentas com sua configuração de Agent, Task, Crew + manual_agent = Agent( + role="Local Task Executor", + goal="Execute a specific local task using a manually managed Stdio tool.", + backstory="An AI proficient in controlling local processes via MCP.", + tools=tools, + verbose=True + ) + + manual_task = Task( + description="Execute the 'perform_analysis' command via the Stdio tool.", + expected_output="Results of the analysis.", + agent=manual_agent + ) + + manual_crew = Crew( + agents=[manual_agent], + tasks=[manual_task], + verbose=True, + process=Process.sequential + ) + + + result = manual_crew.kickoff() # As entradas reais dependem da sua ferramenta + print("\nCrew Task Result (Stdio - Manual):\n", result) + +except Exception as e: + print(f"An error occurred during manual Stdio MCP integration: {e}") +finally: + if mcp_server_adapter and mcp_server_adapter.is_connected: # Verifica se está conectado antes de parar + print("Stopping Stdio MCP server connection (manual)...") + mcp_server_adapter.stop() # **Crucial: Assegure que stop seja chamado** + elif mcp_server_adapter: # Se o adaptador existe mas não está conectado (ex.: start falhou) + print("Stdio MCP server adapter was not connected. No stop needed or start failed.") + +``` + +Lembre-se de substituir caminhos e comandos de exemplo pelos detalhes reais do seu servidor Stdio. O parâmetro `env` em `StdioServerParameters` pode ser usado para definir variáveis de ambiente para o processo do servidor, o que pode ser útil para configurar seu comportamento ou fornecer caminhos necessários (como `PYTHONPATH`). \ No newline at end of file diff --git a/docs/pt-BR/mcp/streamable-http.mdx b/docs/pt-BR/mcp/streamable-http.mdx new file mode 100644 index 000000000..4201e7a83 --- /dev/null +++ b/docs/pt-BR/mcp/streamable-http.mdx @@ -0,0 +1,135 @@ +--- +title: Transporte HTTP Streamable +description: Saiba como conectar o CrewAI a servidores MCP remotos usando o transporte HTTP Streamable flexível. +icon: globe +--- + +## Visão Geral + +O transporte HTTP Streamable oferece uma maneira flexível de se conectar a servidores MCP remotos. Ele é frequentemente baseado em HTTP e pode suportar vários padrões de comunicação, incluindo requisição-resposta e streaming, às vezes utilizando Server-Sent Events (SSE) para fluxos do servidor para o cliente dentro de uma interação HTTP mais ampla. + +## Conceitos-Chave + +- **Servidores Remotos**: Projetado para servidores MCP hospedados remotamente. +- **Flexibilidade**: Pode suportar padrões de interação mais complexos do que SSE puro, potencialmente incluindo comunicação bidirecional se o servidor implementá-la. +- **Configuração do `MCPServerAdapter`**: Você precisará fornecer a URL base do servidor para comunicação MCP e especificar `"streamable-http"` como o tipo de transporte. + +## Conectando via HTTP Streamable + +Você tem dois métodos principais para gerenciar o ciclo de vida da conexão com um servidor MCP HTTP Streamable: + +### 1. Conexão Totalmente Gerenciada (Recomendado) + +A abordagem recomendada é usar um gerenciador de contexto Python (`with` statement), que lida automaticamente com a configuração e encerramento da conexão. + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter + +server_params = { + "url": "http://localhost:8001/mcp", # Replace with your actual Streamable HTTP server URL + "transport": "streamable-http" +} + +try: + with MCPServerAdapter(server_params) as tools: + print(f"Available tools from Streamable HTTP MCP server: {[tool.name for tool in tools]}") + + http_agent = Agent( + role="HTTP Service Integrator", + goal="Utilize tools from a remote MCP server via Streamable HTTP.", + backstory="An AI agent adept at interacting with complex web services.", + tools=tools, + verbose=True, + ) + + http_task = Task( + description="Perform a complex data query using a tool from the Streamable HTTP server.", + expected_output="The result of the complex data query.", + agent=http_agent, + ) + + http_crew = Crew( + agents=[http_agent], + tasks=[http_task], + verbose=True, + process=Process.sequential + ) + + result = http_crew.kickoff() + print("\nCrew Task Result (Streamable HTTP - Managed):\n", result) + +except Exception as e: + print(f"Error connecting to or using Streamable HTTP MCP server (Managed): {e}") + print("Ensure the Streamable HTTP MCP server is running and accessible at the specified URL.") + +``` +**Nota:** Substitua `"http://localhost:8001/mcp"` pela URL real do seu servidor MCP HTTP Streamable. + +### 2. Ciclo de Vida da Conexão Manual + +Para cenários que exigem controle mais explícito, você pode gerenciar a conexão do `MCPServerAdapter` manualmente. + + +É **crítico** chamar `mcp_server_adapter.stop()` quando terminar para fechar a conexão e liberar recursos. Usar um bloco `try...finally` é a forma mais segura de garantir isso. + + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter + +server_params = { + "url": "http://localhost:8001/mcp", # Replace with your actual Streamable HTTP server URL + "transport": "streamable-http" +} + +mcp_server_adapter = None +try: + mcp_server_adapter = MCPServerAdapter(server_params) + mcp_server_adapter.start() + tools = mcp_server_adapter.tools + print(f"Available tools (manual Streamable HTTP): {[tool.name for tool in tools]}") + + manual_http_agent = Agent( + role="Advanced Web Service User", + goal="Interact with an MCP server using manually managed Streamable HTTP connections.", + backstory="An AI specialist in fine-tuning HTTP-based service integrations.", + tools=tools, + verbose=True + ) + + data_processing_task = Task( + description="Submit data for processing and retrieve results via Streamable HTTP.", + expected_output="Processed data or confirmation.", + agent=manual_http_agent + ) + + data_crew = Crew( + agents=[manual_http_agent], + tasks=[data_processing_task], + verbose=True, + process=Process.sequential + ) + + result = data_crew.kickoff() + print("\nCrew Task Result (Streamable HTTP - Manual):\n", result) + +except Exception as e: + print(f"An error occurred during manual Streamable HTTP MCP integration: {e}") + print("Ensure the Streamable HTTP MCP server is running and accessible.") +finally: + if mcp_server_adapter and mcp_server_adapter.is_connected: + print("Stopping Streamable HTTP MCP server connection (manual)...") + mcp_server_adapter.stop() # **Crucial: Ensure stop is called** + elif mcp_server_adapter: + print("Streamable HTTP MCP server adapter was not connected. No stop needed or start failed.") +``` + +## Considerações de Segurança + +Ao utilizar o transporte HTTP Streamable, as melhores práticas gerais de segurança web são fundamentais: +- **Use HTTPS**: Sempre prefira HTTPS (HTTP Seguro) para as URLs do seu servidor MCP para criptografar os dados em trânsito. +- **Autenticação**: Implemente mecanismos robustos de autenticação se seu servidor MCP expuser ferramentas ou dados sensíveis. +- **Validação de Entrada**: Garanta que seu servidor MCP valide todas as requisições e parâmetros recebidos. + +Para um guia abrangente sobre como proteger suas integrações MCP, consulte nossa página de [Considerações de Segurança](./security.mdx) e a documentação oficial de [Segurança em Transportes MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations). \ No newline at end of file diff --git a/docs/pt-BR/observability/agentops.mdx b/docs/pt-BR/observability/agentops.mdx new file mode 100644 index 000000000..e7f13925f --- /dev/null +++ b/docs/pt-BR/observability/agentops.mdx @@ -0,0 +1,126 @@ +--- +title: Integração com AgentOps +description: Entendendo e registrando a performance do seu agente com AgentOps. +icon: paperclip +--- + +# Introdução + +Observabilidade é um aspecto fundamental no desenvolvimento e implantação de agentes de IA conversacional. Ela permite que desenvolvedores compreendam como seus agentes estão performando, +como eles estão interagindo com os usuários e como utilizam ferramentas externas e APIs. +AgentOps é um produto independente do CrewAI que fornece uma solução completa de observabilidade para agentes. + +## AgentOps + +[AgentOps](https://agentops.ai/?=crew) oferece replay de sessões, métricas e monitoramento para agentes. + +Em um alto nível, o AgentOps oferece a capacidade de monitorar custos, uso de tokens, latência, falhas do agente, estatísticas de sessão e muito mais. +Para mais informações, confira o [Repositório do AgentOps](https://github.com/AgentOps-AI/agentops). + +### Visão Geral + +AgentOps fornece monitoramento para agentes em desenvolvimento e produção. +Disponibiliza um dashboard para acompanhamento de performance dos agentes, replay de sessões e relatórios personalizados. + +Além disso, o AgentOps traz análises detalhadas das sessões para visualizar interações do agente Crew, chamadas LLM e uso de ferramentas em tempo real. +Esse recurso é útil para depuração e entendimento de como os agentes interagem com usuários e entre si. + +![Visão geral de uma série selecionada de execuções de sessões do agente](/images/agentops-overview.png) +![Visão geral das análises detalhadas de sessões para examinar execuções de agentes](/images/agentops-session.png) +![Visualizando um gráfico de execução passo a passo do replay do agente](/images/agentops-replay.png) + +### Funcionalidades + +- **Gerenciamento e Rastreamento de Custos de LLM**: Acompanhe gastos com provedores de modelos fundamentais. +- **Análises de Replay**: Assista gráficos de execução do agente, passo a passo. +- **Detecção de Pensamento Recursivo**: Identifique quando agentes entram em loops infinitos. +- **Relatórios Personalizados**: Crie análises customizadas sobre a performance dos agentes. +- **Dashboard Analítico**: Monitore estatísticas gerais de agentes em desenvolvimento e produção. +- **Teste de Modelos Públicos**: Teste seus agentes em benchmarks e rankings. +- **Testes Personalizados**: Execute seus agentes em testes específicos de domínio. +- **Depuração com Viagem no Tempo**: Reinicie suas sessões a partir de checkpoints. +- **Conformidade e Segurança**: Crie registros de auditoria e detecte possíveis ameaças como uso de palavrões e vazamento de dados pessoais. +- **Detecção de Prompt Injection**: Identifique possíveis injeções de código e vazamentos de segredos. + +### Utilizando o AgentOps + + + + Crie uma chave de API de usuário aqui: [Create API Key](https://app.agentops.ai/account) + + + Adicione sua chave API nas variáveis de ambiente: + ```bash + AGENTOPS_API_KEY= + ``` + + + Instale o AgentOps com: + ```bash + pip install 'crewai[agentops]' + ``` + ou + ```bash + pip install agentops + ``` + + + Antes de utilizar o `Crew` no seu script, inclua estas linhas: + + ```python + import agentops + agentops.init() + ``` + + Isso irá iniciar uma sessão do AgentOps e também rastrear automaticamente os agentes Crew. Para mais detalhes sobre como adaptar sistemas de agentes mais complexos, + confira a [documentação do AgentOps](https://docs.agentops.ai) ou participe do [Discord](https://discord.gg/j4f3KbeH). + + + +### Exemplos de Crew + AgentOps + + + + Exemplo de um agente Crew que gera vagas de emprego. + + + Exemplo de um agente Crew que valida arquivos Markdown. + + + Exemplo de um agente Crew que gera posts para Instagram. + + + +### Mais Informações + +Para começar, crie uma [conta AgentOps](https://agentops.ai/?=crew). + +Para sugestões de funcionalidades ou relatos de bugs, entre em contato com o time do AgentOps pelo [Repositório do AgentOps](https://github.com/AgentOps-AI/agentops). + +#### Links Extras + +🐦 Twitter +  •   +📢 Discord +  •   +🖇️ Dashboard AgentOps +  •   +📙 Documentação \ No newline at end of file diff --git a/docs/pt-BR/observability/arize-phoenix.mdx b/docs/pt-BR/observability/arize-phoenix.mdx new file mode 100644 index 000000000..fade391ec --- /dev/null +++ b/docs/pt-BR/observability/arize-phoenix.mdx @@ -0,0 +1,151 @@ +--- +title: Arize Phoenix +description: Integração do Arize Phoenix para CrewAI com OpenTelemetry e OpenInference +icon: magnifying-glass-chart +--- + +# Integração com Arize Phoenix + +Este guia demonstra como integrar o **Arize Phoenix** ao **CrewAI** usando o OpenTelemetry através do [OpenInference](https://github.com/openinference/openinference) SDK. Ao final deste guia, você será capaz de rastrear seus agentes CrewAI e depurá-los com facilidade. + +> **O que é o Arize Phoenix?** O [Arize Phoenix](https://phoenix.arize.com) é uma plataforma de observabilidade de LLM que oferece rastreamento e avaliação para aplicações de IA. + +[![Assista a um vídeo demonstrando a nossa integração com o Phoenix](https://storage.googleapis.com/arize-assets/fixtures/setup_crewai.png)](https://www.youtube.com/watch?v=Yc5q3l6F7Ww) + +## Primeiros Passos + +Vamos percorrer um exemplo simples de uso do CrewAI e integração com o Arize Phoenix via OpenTelemetry utilizando o OpenInference. + +Você também pode acessar este guia no [Google Colab](https://colab.research.google.com/github/Arize-ai/phoenix/blob/main/tutorials/tracing/crewai_tracing_tutorial.ipynb). + +### Passo 1: Instale as Dependências + +```bash +pip install openinference-instrumentation-crewai crewai crewai-tools arize-phoenix-otel +``` + +### Passo 2: Configure as Variáveis de Ambiente + +Configure as chaves de API do Phoenix Cloud e ajuste o OpenTelemetry para enviar rastros ao Phoenix. O Phoenix Cloud é uma versão hospedada do Arize Phoenix, mas não é obrigatório para utilizar esta integração. + +Você pode obter uma chave de API gratuita do Serper [aqui](https://serper.dev/). + +```python +import os +from getpass import getpass + +# Obtenha suas credenciais do Phoenix Cloud +PHOENIX_API_KEY = getpass("🔑 Digite sua Phoenix Cloud API Key: ") + +# Obtenha as chaves de API para os serviços +OPENAI_API_KEY = getpass("🔑 Digite sua OpenAI API key: ") +SERPER_API_KEY = getpass("🔑 Digite sua Serper API key: ") + +# Defina as variáveis de ambiente +os.environ["PHOENIX_CLIENT_HEADERS"] = f"api_key={PHOENIX_API_KEY}" +os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "https://app.phoenix.arize.com" # Phoenix Cloud, altere para seu endpoint se estiver utilizando uma instância self-hosted +os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY +os.environ["SERPER_API_KEY"] = SERPER_API_KEY +``` + +### Passo 3: Inicialize o OpenTelemetry com o Phoenix + +Inicialize o SDK de instrumentação OpenTelemetry do OpenInference para começar a capturar rastros e enviá-los ao Phoenix. + +```python +from phoenix.otel import register + +tracer_provider = register( + project_name="crewai-tracing-demo", + auto_instrument=True, +) +``` + +### Passo 4: Crie uma Aplicação CrewAI + +Vamos criar uma aplicação CrewAI em que dois agentes colaboram para pesquisar e escrever um post de blog sobre avanços em IA. + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool +from openinference.instrumentation.crewai import CrewAIInstrumentor +from phoenix.otel import register + +# configure o monitoramento para seu crew +tracer_provider = register( + endpoint="http://localhost:6006/v1/traces") +CrewAIInstrumentor().instrument(skip_dep_check=True, tracer_provider=tracer_provider) +search_tool = SerperDevTool() + +# Defina seus agentes com papéis e objetivos +researcher = Agent( + role="Senior Research Analyst", + goal="Uncover cutting-edge developments in AI and data science", + backstory="""You work at a leading tech think tank. + Your expertise lies in identifying emerging trends. + You have a knack for dissecting complex data and presenting actionable insights.""", + verbose=True, + allow_delegation=False, + # You can pass an optional llm attribute specifying what model you wanna use. + # llm=ChatOpenAI(model_name="gpt-3.5", temperature=0.7), + tools=[search_tool], +) +writer = Agent( + role="Tech Content Strategist", + goal="Craft compelling content on tech advancements", + backstory="""You are a renowned Content Strategist, known for your insightful and engaging articles. + You transform complex concepts into compelling narratives.""", + verbose=True, + allow_delegation=True, +) + +# Crie tarefas para seus agentes +task1 = Task( + description="""Conduct a comprehensive analysis of the latest advancements in AI in 2024. + Identify key trends, breakthrough technologies, and potential industry impacts.""", + expected_output="Full analysis report in bullet points", + agent=researcher, +) + +task2 = Task( + description="""Using the insights provided, develop an engaging blog + post that highlights the most significant AI advancements. + Your post should be informative yet accessible, catering to a tech-savvy audience. + Make it sound cool, avoid complex words so it doesn't sound like AI.""", + expected_output="Full blog post of at least 4 paragraphs", + agent=writer, +) + +# Instancie seu crew com um processo sequencial +crew = Crew( + agents=[researcher, writer], tasks=[task1, task2], verbose=1, process=Process.sequential +) + +# Coloque seu crew para trabalhar! +result = crew.kickoff() + +print("######################") +print(result) +``` + +### Passo 5: Visualize os Rastros no Phoenix + +Após executar o agente, você poderá visualizar os rastros gerados pela sua aplicação CrewAI no Phoenix. Você verá etapas detalhadas das interações dos agentes e chamadas de LLM, o que pode ajudar na depuração e otimização dos seus agentes de IA. + +Acesse sua conta Phoenix Cloud e navegue até o projeto que você especificou no parâmetro `project_name`. Você verá uma visualização de linha do tempo do seu rastro, incluindo todas as interações dos agentes, uso de ferramentas e chamadas LLM. + +![Exemplo de rastro no Phoenix mostrando interações de agentes](https://storage.googleapis.com/arize-assets/fixtures/crewai_traces.png) + + +### Informações de Compatibilidade de Versão +- Python 3.8+ +- CrewAI >= 0.86.0 +- Arize Phoenix >= 7.0.1 +- OpenTelemetry SDK >= 1.31.0 + + +### Referências +- [Documentação do Phoenix](https://docs.arize.com/phoenix/) - Visão geral da plataforma Phoenix. +- [Documentação do CrewAI](https://docs.crewai.com/) - Visão geral do framework CrewAI. +- [Documentação do OpenTelemetry](https://opentelemetry.io/docs/) - Guia do OpenTelemetry +- [OpenInference GitHub](https://github.com/openinference/openinference) - Código-fonte do SDK OpenInference. \ No newline at end of file diff --git a/docs/pt-BR/observability/langfuse.mdx b/docs/pt-BR/observability/langfuse.mdx new file mode 100644 index 000000000..3423bae72 --- /dev/null +++ b/docs/pt-BR/observability/langfuse.mdx @@ -0,0 +1,107 @@ +--- +title: Integração Langfuse +description: Saiba como integrar o Langfuse ao CrewAI via OpenTelemetry usando OpenLit +icon: vials +--- + +# Integre o Langfuse ao CrewAI + +Este notebook demonstra como integrar o **Langfuse** ao **CrewAI** usando OpenTelemetry via o SDK **OpenLit**. Ao final deste notebook, você será capaz de rastrear suas aplicações CrewAI com o Langfuse para melhorar a observabilidade e a depuração. + +> **O que é Langfuse?** [Langfuse](https://langfuse.com) é uma plataforma open-source de engenharia LLM. Ela fornece recursos de rastreamento e monitoramento para aplicações LLM, ajudando desenvolvedores a depurar, analisar e otimizar seus sistemas de IA. O Langfuse se integra com várias ferramentas e frameworks através de integrações nativas, OpenTelemetry e APIs/SDKs. + +[![Vídeo de Visão Geral do Langfuse](https://github.com/user-attachments/assets/3926b288-ff61-4b95-8aa1-45d041c70866)](https://langfuse.com/watch-demo) + +## Primeiros Passos + +Vamos passar por um exemplo simples usando CrewAI e integrando ao Langfuse via OpenTelemetry utilizando o OpenLit. + +### Passo 1: Instale as Dependências + +```python +%pip install langfuse openlit crewai crewai_tools +``` + +### Passo 2: Configure as Variáveis de Ambiente + +Defina suas chaves de API do Langfuse e configure as opções de exportação do OpenTelemetry para enviar os traces ao Langfuse. Consulte a [Documentação Langfuse OpenTelemetry](https://langfuse.com/docs/opentelemetry/get-started) para mais informações sobre o endpoint Langfuse OpenTelemetry `/api/public/otel` e autenticação. + +```python +import os + +# Obtenha as chaves do seu projeto na página de configurações do projeto: https://cloud.langfuse.com +os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..." +os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..." +os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" # 🇪🇺 Região UE +# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 Região EUA + + +# Sua chave OpenAI +os.environ["OPENAI_API_KEY"] = "sk-proj-..." +``` +Com as variáveis de ambiente configuradas, agora podemos inicializar o cliente Langfuse. A função get_client() inicializa o cliente Langfuse usando as credenciais fornecidas nas variáveis de ambiente. + +```python +from langfuse import get_client + +langfuse = get_client() + +# Verificar conexão +if langfuse.auth_check(): + print("Cliente Langfuse autenticado e pronto!") +else: + print("Falha na autenticação. Verifique suas credenciais e host.") +``` + +### Passo 3: Inicialize o OpenLit + +Inicialize o SDK de instrumentação OpenTelemetry do OpenLit para começar a capturar traces do OpenTelemetry. + +```python +import openlit + +openlit.init() +``` + +### Passo 4: Crie uma Aplicação Simples CrewAI + +Vamos criar uma aplicação simples CrewAI onde múltiplos agentes colaboram para responder à pergunta de um usuário. + +```python +from crewai import Agent, Task, Crew + +from crewai_tools import ( + WebsiteSearchTool +) + +web_rag_tool = WebsiteSearchTool() + +writer = Agent( + role="Writer", + goal="Você torna a matemática envolvente e compreensível para crianças pequenas através de poesias", + backstory="Você é especialista em escrever haicais mas não sabe nada de matemática.", + tools=[web_rag_tool], + ) + +task = Task(description=("O que é {multiplicação}?"), + expected_output=("Componha um haicai que inclua a resposta."), + agent=writer) + +crew = Crew( + agents=[writer], + tasks=[task], + share_crew=False +) +``` + +### Passo 5: Veja os Traces no Langfuse + +Após rodar o agente, você pode visualizar os traces gerados pela sua aplicação CrewAI no [Langfuse](https://cloud.langfuse.com). Você verá etapas detalhadas das interações do LLM, o que pode ajudar na depuração e otimização do seu agente de IA. + +![Exemplo de trace CrewAI no Langfuse](https://langfuse.com/images/cookbook/integration_crewai/crewai-example-trace.png) + +_[Exemplo público de trace no Langfuse](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/e2cf380ffc8d47d28da98f136140642b?timestamp=2025-02-05T15%3A12%3A02.717Z&observation=3b32338ee6a5d9af)_ + +## Referências + +- [Documentação Langfuse OpenTelemetry](https://langfuse.com/docs/opentelemetry/get-started) \ No newline at end of file diff --git a/docs/pt-BR/observability/langtrace.mdx b/docs/pt-BR/observability/langtrace.mdx new file mode 100644 index 000000000..e2e5ecd80 --- /dev/null +++ b/docs/pt-BR/observability/langtrace.mdx @@ -0,0 +1,72 @@ +--- +title: Integração com Langtrace +description: Como monitorar custo, latência e desempenho dos Agentes CrewAI usando o Langtrace, uma ferramenta externa de observabilidade. +icon: chart-line +--- + +# Visão Geral do Langtrace + +O Langtrace é uma ferramenta externa e open-source que auxilia na configuração de observabilidade e avaliações para Modelos de Linguagem de Grande Porte (LLMs), frameworks de LLM e Bancos de Dados Vetoriais. +Apesar de não ser integrado diretamente ao CrewAI, o Langtrace pode ser utilizado em conjunto com o CrewAI para fornecer uma visibilidade aprofundada sobre o custo, latência e desempenho dos seus Agentes CrewAI. +Essa integração permite o registro de hiperparâmetros, o monitoramento de regressões de desempenho e o estabelecimento de um processo de melhoria contínua dos seus Agentes. + +![Visão geral de uma seleção de execuções de sessões de agentes](/images/langtrace1.png) +![Visão geral dos traces de agentes](/images/langtrace2.png) +![Visão detalhada dos traces de LLM](/images/langtrace3.png) + +## Instruções de Configuração + + + + Cadastre-se acessando [https://langtrace.ai/signup](https://langtrace.ai/signup). + + + Defina o tipo do projeto como `CrewAI` e gere uma chave de API. + + + Use o seguinte comando: + + ```bash + pip install langtrace-python-sdk + ``` + + + Importe e inicialize o Langtrace no início do seu script, antes de quaisquer imports do CrewAI: + + ```python + from langtrace_python_sdk import langtrace + langtrace.init(api_key='') + + # Agora importe os módulos do CrewAI + from crewai import Agent, Task, Crew + ``` + + + +### Funcionalidades e Sua Aplicação no CrewAI + +1. **Rastreamento de Token e Custo do LLM** + + - Monitore o uso de tokens e os custos associados para cada interação dos agentes CrewAI. + +2. **Gráfico de Trace para Etapas de Execução** + + - Visualize o fluxo de execução das suas tarefas CrewAI, incluindo latência e logs. + - Útil para identificar gargalos nos fluxos de trabalho dos seus agentes. + +3. **Curadoria de Dataset com Anotação Manual** + + - Crie conjuntos de dados a partir das saídas das suas tarefas CrewAI para futuros treinamentos ou avaliações. + +4. **Versionamento e Gerenciamento de Prompt** + + - Acompanhe as diferentes versões de prompts utilizados em seus agentes CrewAI. + - Útil para testes A/B e otimização de desempenho dos agentes. + +5. **Playground de Prompt com Comparações de Modelos** + + - Teste e compare diferentes prompts e modelos para seus agentes CrewAI antes da implantação. + +6. **Testes e Avaliações** + + - Configure testes automatizados para seus agentes e tarefas CrewAI. \ No newline at end of file diff --git a/docs/pt-BR/observability/maxim.mdx b/docs/pt-BR/observability/maxim.mdx new file mode 100644 index 000000000..84271b3ea --- /dev/null +++ b/docs/pt-BR/observability/maxim.mdx @@ -0,0 +1,150 @@ +--- +title: Integração Maxim +description: Inicie o monitoramento, avaliação e observabilidade de agentes +icon: bars-staggered +--- + +# Integração Maxim + +Maxim AI oferece monitoramento completo de agentes, avaliação e observabilidade para suas aplicações CrewAI. Com a integração de uma linha do Maxim, você pode facilmente rastrear e analisar interações dos agentes, métricas de desempenho e muito mais. + +## Funcionalidades: Integração com Uma Linha + +- **Rastreamento de Agentes de Ponta a Ponta**: Monitore todo o ciclo de vida dos seus agentes +- **Análise de Desempenho**: Acompanhe latência, tokens consumidos e custos +- **Monitoramento de Hiperparâmetros**: Visualize detalhes de configuração das execuções dos agentes +- **Rastreamento de Chamadas de Ferramentas**: Observe quando e como os agentes usam suas ferramentas +- **Visualização Avançada**: Entenda as trajetórias dos agentes através de dashboards intuitivos + +## Começando + +### Pré-requisitos + +- Python versão >=3.10 +- Uma conta Maxim ([cadastre-se aqui](https://getmaxim.ai/)) +- Um projeto CrewAI + +### Instalação + +Instale o SDK do Maxim via pip: + +```python +pip install maxim-py>=3.6.2 +``` + +Ou adicione ao seu `requirements.txt`: + +``` +maxim-py>=3.6.2 +``` + +### Configuração Básica + +### 1. Configure as variáveis de ambiente + +```python +### Configuração de Variáveis de Ambiente + +# Crie um arquivo `.env` na raiz do seu projeto: + +# Configuração da API Maxim +MAXIM_API_KEY=your_api_key_here +MAXIM_LOG_REPO_ID=your_repo_id_here +``` + +### 2. Importe os pacotes necessários + +```python +from crewai import Agent, Task, Crew, Process +from maxim import Maxim +from maxim.logger.crewai import instrument_crewai +``` + +### 3. Inicialize o Maxim com sua chave de API + +```python +# Inicialize o logger do Maxim +logger = Maxim().logger() + +# Instrumente o CrewAI com apenas uma linha +instrument_crewai(logger) +``` + +### 4. Crie e execute sua aplicação CrewAI normalmente + +```python + +# Crie seu agente +researcher = Agent( + role='Senior Research Analyst', + goal='Uncover cutting-edge developments in AI', + backstory="You are an expert researcher at a tech think tank...", + verbose=True, + llm=llm +) + +# Defina a tarefa +research_task = Task( + description="Research the latest AI advancements...", + expected_output="", + agent=researcher +) + +# Configure e execute a crew +crew = Crew( + agents=[researcher], + tasks=[research_task], + verbose=True +) + +try: + result = crew.kickoff() +finally: + maxim.cleanup() # Garanta o cleanup mesmo em caso de erros +``` + +É isso! Todas as interações dos seus agentes CrewAI agora serão registradas e estarão disponíveis em seu painel Maxim. + +Confira este Google Colab Notebook para referência rápida – [Notebook](https://colab.research.google.com/drive/1ZKIZWsmgQQ46n8TH9zLsT1negKkJA6K8?usp=sharing) + +## Visualizando Seus Rastreamentos + +Após executar sua aplicação CrewAI: + +![Exemplo de rastreamento no Maxim mostrando interações de agentes](https://raw.githubusercontent.com/maximhq/maxim-docs/master/images/Screenshot2025-05-14at12.10.58PM.png) + +1. Faça login no seu [Painel Maxim](https://getmaxim.ai/dashboard) +2. Navegue até seu repositório +3. Visualize rastreamentos detalhados de agentes, incluindo: + - Conversas dos agentes + - Padrões de uso de ferramentas + - Métricas de desempenho + - Análises de custos + +## Solução de Problemas + +### Problemas Comuns + +- **Nenhum rastreamento aparecendo**: Certifique-se de que sua chave de API e o ID do repositório estão corretos +- Certifique-se de que você **chamou `instrument_crewai()`** ***antes*** de executar sua crew. Isso inicializa corretamente os hooks de logging. +- Defina `debug=True` na chamada do `instrument_crewai()` para expor erros internos: + + ```python + instrument_crewai(logger, debug=True) + ``` + +- Configure seus agentes com `verbose=True` para capturar logs detalhados: + + ```python + + agent = CrewAgent(..., verbose=True) + ``` + +- Verifique cuidadosamente se `instrument_crewai()` foi chamado **antes** de criar ou executar agentes. Isso pode parecer óbvio, mas é um erro comum. + +### Suporte + +Se você encontrar algum problema: + +- Consulte a [Documentação do Maxim](https://getmaxim.ai/docs) +- Maxim Github [Link](https://github.com/maximhq) \ No newline at end of file diff --git a/docs/pt-BR/observability/mlflow.mdx b/docs/pt-BR/observability/mlflow.mdx new file mode 100644 index 000000000..e1845cccd --- /dev/null +++ b/docs/pt-BR/observability/mlflow.mdx @@ -0,0 +1,205 @@ +--- +title: Integração com MLflow +description: Comece rapidamente a monitorar seus Agents com MLflow. +icon: bars-staggered +--- + +# Visão Geral do MLflow + +[MLflow](https://mlflow.org/) é uma plataforma open-source que auxilia profissionais e equipes de machine learning a lidar com as complexidades do processo de aprendizagem de máquina. + +Ela oferece um recurso de tracing que aprimora a observabilidade de LLMs em suas aplicações de IA Generativa, capturando informações detalhadas sobre a execução dos serviços de sua aplicação. +O tracing fornece uma forma de registrar os inputs, outputs e metadados associados a cada etapa intermediária de uma requisição, permitindo que você identifique facilmente a origem de bugs e comportamentos inesperados. + +![Visão geral do uso de tracing MLflow com crewAI](/images/mlflow-tracing.gif) + +### Funcionalidades + +- **Painel de Tracing**: Monitore as atividades dos seus agentes crewAI com painéis detalhados que incluem entradas, saídas e metadados dos spans. +- **Tracing Automatizado**: Uma integração totalmente automatizada com crewAI, que pode ser habilitada executando `mlflow.crewai.autolog()`. +- **Instrumentação Manual de Tracing com pouco esforço**: Personalize a instrumentação dos traces usando as APIs de alto nível do MLflow, como decorators, wrappers de funções e context managers. +- **Compatibilidade com OpenTelemetry**: O MLflow Tracing suporta a exportação de traces para um OpenTelemetry Collector, que pode então ser usado para exportar traces para diversos backends como Jaeger, Zipkin e AWS X-Ray. +- **Empacote e Faça Deploy dos Agents**: Empacote e faça deploy de seus agents crewAI em um servidor de inferência com diversas opções de destino. +- **Hospede LLMs com Segurança**: Hospede múltiplos LLMs de vários provedores em um endpoint unificado através do gateway do MFflow. +- **Avaliação**: Avalie seus agents crewAI com uma ampla variedade de métricas utilizando a API conveniente `mlflow.evaluate()`. + +## Instruções de Configuração + + + + ```shell + # A integração crewAI está disponível no mlflow>=2.19.0 + pip install mlflow + ``` + + + ```shell + # Este processo é opcional, mas é recomendado utilizar o servidor de tracking do MLflow para melhor visualização e mais funcionalidades. + mlflow server + ``` + + + Adicione as duas linhas a seguir ao código da sua aplicação: + + ```python + import mlflow + + mlflow.crewai.autolog() + + # Opcional: Defina uma tracking URI e um nome de experimento caso utilize um servidor de tracking + mlflow.set_tracking_uri("http://localhost:5000") + mlflow.set_experiment("CrewAI") + ``` + + Exemplo de uso para tracing de Agents do CrewAI: + + ```python + from crewai import Agent, Crew, Task + from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + from crewai_tools import SerperDevTool, WebsiteSearchTool + + from textwrap import dedent + + content = "Users name is John. He is 30 years old and lives in San Francisco." + string_source = StringKnowledgeSource( + content=content, metadata={"preference": "personal"} + ) + + search_tool = WebsiteSearchTool() + + + class TripAgents: + def city_selection_agent(self): + return Agent( + role="City Selection Expert", + goal="Select the best city based on weather, season, and prices", + backstory="An expert in analyzing travel data to pick ideal destinations", + tools=[ + search_tool, + ], + verbose=True, + ) + + def local_expert(self): + return Agent( + role="Local Expert at this city", + goal="Provide the BEST insights about the selected city", + backstory="""A knowledgeable local guide with extensive information + about the city, it's attractions and customs""", + tools=[search_tool], + verbose=True, + ) + + + class TripTasks: + def identify_task(self, agent, origin, cities, interests, range): + return Task( + description=dedent( + f""" + Analyze and select the best city for the trip based + on specific criteria such as weather patterns, seasonal + events, and travel costs. This task involves comparing + multiple cities, considering factors like current weather + conditions, upcoming cultural or seasonal events, and + overall travel expenses. + Your final answer must be a detailed + report on the chosen city, and everything you found out + about it, including the actual flight costs, weather + forecast and attractions. + + Traveling from: {origin} + City Options: {cities} + Trip Date: {range} + Traveler Interests: {interests} + """ + ), + agent=agent, + expected_output="Detailed report on the chosen city including flight costs, weather forecast, and attractions", + ) + + def gather_task(self, agent, origin, interests, range): + return Task( + description=dedent( + f""" + As a local expert on this city you must compile an + in-depth guide for someone traveling there and wanting + to have THE BEST trip ever! + Gather information about key attractions, local customs, + special events, and daily activity recommendations. + Find the best spots to go to, the kind of place only a + local would know. + This guide should provide a thorough overview of what + the city has to offer, including hidden gems, cultural + hotspots, must-visit landmarks, weather forecasts, and + high level costs. + The final answer must be a comprehensive city guide, + rich in cultural insights and practical tips, + tailored to enhance the travel experience. + + Trip Date: {range} + Traveling from: {origin} + Traveler Interests: {interests} + """ + ), + agent=agent, + expected_output="Comprehensive city guide including hidden gems, cultural hotspots, and practical travel tips", + ) + + + class TripCrew: + def __init__(self, origin, cities, date_range, interests): + self.cities = cities + self.origin = origin + self.interests = interests + self.date_range = date_range + + def run(self): + agents = TripAgents() + tasks = TripTasks() + + city_selector_agent = agents.city_selection_agent() + local_expert_agent = agents.local_expert() + + identify_task = tasks.identify_task( + city_selector_agent, + self.origin, + self.cities, + self.interests, + self.date_range, + ) + gather_task = tasks.gather_task( + local_expert_agent, self.origin, self.interests, self.date_range + ) + + crew = Crew( + agents=[city_selector_agent, local_expert_agent], + tasks=[identify_task, gather_task], + verbose=True, + memory=True, + knowledge={ + "sources": [string_source], + "metadata": {"preference": "personal"}, + }, + ) + + result = crew.kickoff() + return result + + + trip_crew = TripCrew("California", "Tokyo", "Dec 12 - Dec 20", "sports") + result = trip_crew.run() + + print(result) + ``` + Consulte a [Documentação de Tracing do MLflow](https://mlflow.org/docs/latest/llms/tracing/index.html) para mais configurações e casos de uso. + + + Agora os traces dos seus agentes crewAI estão sendo capturados pelo MLflow. + Vamos acessar o servidor de tracking do MLflow para visualizar os traces e obter insights dos seus Agents. + + Abra `127.0.0.1:5000` em seu navegador para acessar o servidor de tracking do MLflow. + + Exemplo de tracing do MLflow com crewai + + + \ No newline at end of file diff --git a/docs/pt-BR/observability/openlit.mdx b/docs/pt-BR/observability/openlit.mdx new file mode 100644 index 000000000..7f07b345a --- /dev/null +++ b/docs/pt-BR/observability/openlit.mdx @@ -0,0 +1,180 @@ +--- +title: Integração OpenLIT +description: Comece a monitorar seus Agentes rapidamente com apenas uma linha de código usando OpenTelemetry. +icon: magnifying-glass-chart +--- + +# Visão Geral do OpenLIT + +[OpenLIT](https://github.com/openlit/openlit?src=crewai-docs) é uma ferramenta open-source que simplifica o monitoramento de desempenho de agentes de IA, LLMs, VectorDBs e GPUs com apenas **uma** linha de código. + +Ela oferece rastreamento e métricas nativos do OpenTelemetry para acompanhar parâmetros importantes como custo, latência, interações e sequências de tarefas. +Essa configuração permite acompanhar hiperparâmetros e monitorar problemas de desempenho, ajudando a encontrar formas de aprimorar e refinar seus agentes com o tempo. + + + Visão geral do uso de agentes, incluindo custo e tokens + Visão geral dos rastreamentos e métricas otel do agente + Visão detalhada dos rastreamentos do agente + + +### Funcionalidades + +- **Painel Analítico**: Monitore a saúde e desempenho dos seus Agentes com dashboards detalhados que acompanham métricas, custos e interações dos usuários. +- **SDK de Observabilidade Nativo OpenTelemetry**: SDKs neutros de fornecedor para enviar rastreamentos e métricas para suas ferramentas de observabilidade existentes como Grafana, DataDog e outros. +- **Rastreamento de Custos para Modelos Customizados e Ajustados**: Adapte estimativas de custo para modelos específicos usando arquivos de precificação customizados para orçamentos precisos. +- **Painel de Monitoramento de Exceções**: Identifique e solucione rapidamente problemas ao rastrear exceções comuns e erros por meio de um painel de monitoramento. +- **Conformidade e Segurança**: Detecte ameaças potenciais como profanidade e vazamento de dados sensíveis (PII). +- **Detecção de Prompt Injection**: Identifique possíveis injeções de código e vazamentos de segredos. +- **Gerenciamento de Chaves de API e Segredos**: Gerencie suas chaves de API e segredos do LLM de forma centralizada e segura, evitando práticas inseguras. +- **Gerenciamento de Prompt**: Gerencie e versiona prompts de Agente usando o PromptHub para acesso consistente e fácil entre os agentes. +- **Model Playground** Teste e compare diferentes modelos para seus agentes CrewAI antes da implantação. + +## Instruções de Configuração + + + + + + ```shell + git clone git@github.com:openlit/openlit.git + ``` + + + A partir do diretório raiz do [Repositório OpenLIT](https://github.com/openlit/openlit), execute o comando abaixo: + ```shell + docker compose up -d + ``` + + + + + ```shell + pip install openlit + ``` + + + Adicione as duas linhas abaixo ao seu código de aplicação: + + + ```python + import openlit + openlit.init(otlp_endpoint="http://127.0.0.1:4318") + ``` + + Exemplo de uso para monitoramento de um Agente CrewAI: + + ```python + from crewai import Agent, Task, Crew, Process + import openlit + + openlit.init(disable_metrics=True) + # Definir seus agentes + researcher = Agent( + role="Researcher", + goal="Conduct thorough research and analysis on AI and AI agents", + backstory="You're an expert researcher, specialized in technology, software engineering, AI, and startups. You work as a freelancer and are currently researching for a new client.", + allow_delegation=False, + llm='command-r' + ) + + + # Definir sua task + task = Task( + description="Generate a list of 5 interesting ideas for an article, then write one captivating paragraph for each idea that showcases the potential of a full article on this topic. Return the list of ideas with their paragraphs and your notes.", + expected_output="5 bullet points, each with a paragraph and accompanying notes.", + ) + + # Definir o agente gerente + manager = Agent( + role="Project Manager", + goal="Efficiently manage the crew and ensure high-quality task completion", + backstory="You're an experienced project manager, skilled in overseeing complex projects and guiding teams to success. Your role is to coordinate the efforts of the crew members, ensuring that each task is completed on time and to the highest standard.", + allow_delegation=True, + llm='command-r' + ) + + # Instanciar sua crew com um manager personalizado + crew = Crew( + agents=[researcher], + tasks=[task], + manager_agent=manager, + process=Process.hierarchical, + ) + + # Iniciar o trabalho da crew + result = crew.kickoff() + + print(result) + ``` + + + + Adicione as duas linhas abaixo ao seu código de aplicação: + ```python + import openlit + + openlit.init() + ``` + + Execute o seguinte comando para configurar o endpoint de exportação OTEL: + ```shell + export OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4318" + ``` + + Exemplo de uso para monitoramento de um Agente CrewAI Async: + + ```python + import asyncio + from crewai import Crew, Agent, Task + import openlit + + openlit.init(otlp_endpoint="http://127.0.0.1:4318") + + # Criar um agente com execução de código habilitada + coding_agent = Agent( + role="Python Data Analyst", + goal="Analyze data and provide insights using Python", + backstory="You are an experienced data analyst with strong Python skills.", + allow_code_execution=True, + llm="command-r" + ) + + # Criar uma task que exige execução de código + data_analysis_task = Task( + description="Analyze the given dataset and calculate the average age of participants. Ages: {ages}", + agent=coding_agent, + expected_output="5 bullet points, each with a paragraph and accompanying notes.", + ) + + # Criar uma crew e adicionar a task + analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] + ) + + # Função async para iniciar a crew de forma assíncrona + async def async_crew_execution(): + result = await analysis_crew.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + + # Executar a função async + asyncio.run(async_crew_execution()) + ``` + + + Consulte o [repositório do SDK Python do OpenLIT](https://github.com/openlit/openlit/tree/main/sdk/python) para configurações e casos de uso avançados. + + + Com os dados de Observabilidade dos Agentes agora sendo coletados e enviados ao OpenLIT, o próximo passo é visualizar e analisar esses dados para obter insights sobre o desempenho, comportamento e identificar oportunidades de melhoria dos seus Agentes. + + Basta acessar o OpenLIT em `127.0.0.1:3000` no seu navegador para começar a explorar. Você pode fazer login usando as credenciais padrão + - **Email**: `user@openlit.io` + - **Senha**: `openlituser` + + + Visão geral do uso de agentes, incluindo custo e tokens + Visão geral dos rastreamentos e métricas otel do agente + + + + \ No newline at end of file diff --git a/docs/pt-BR/observability/opik.mdx b/docs/pt-BR/observability/opik.mdx new file mode 100644 index 000000000..16479318f --- /dev/null +++ b/docs/pt-BR/observability/opik.mdx @@ -0,0 +1,129 @@ +--- +title: Integração Opik +description: Saiba como usar o Comet Opik para depurar, avaliar e monitorar suas aplicações CrewAI com rastreamento abrangente, avaliações automatizadas e dashboards prontos para produção. +icon: meteor +--- + +# Visão Geral do Opik + +Com o [Comet Opik](https://www.comet.com/docs/opik/), depure, avalie e monitore suas aplicações LLM, sistemas RAG e fluxos de trabalho agentic com rastreamento detalhado, avaliações automatizadas e dashboards prontos para produção. + + + Exemplo de monitoramento de agente Opik com CrewAI + + +O Opik oferece suporte abrangente para cada etapa do desenvolvimento da sua aplicação CrewAI: + +- **Registrar Traces e Spans**: Acompanhe automaticamente chamadas LLM e lógica da aplicação para depurar e analisar sistemas em desenvolvimento e em produção. Anote manualmente ou programaticamente, visualize e compare respostas entre projetos. +- **Avalie a Performance da sua Aplicação LLM**: Avalie contra um conjunto de testes personalizado e execute métricas de avaliação nativas ou defina suas próprias métricas via SDK ou UI. +- **Teste no Pipeline CI/CD**: Estabeleça bases de performance confiáveis com os testes unitários LLM do Opik, baseados em PyTest. Execute avaliações online para monitoramento contínuo em produção. +- **Monitore & Analise Dados de Produção**: Entenda a performance dos seus modelos em dados inéditos em produção e gere conjuntos de dados para novas iterações de desenvolvimento. + +## Configuração +A Comet oferece uma versão hospedada da plataforma Opik, ou você pode rodar a plataforma localmente. + +Para usar a versão hospedada, basta [criar uma conta gratuita na Comet](https://www.comet.com/signup?utm_medium=github&utm_source=crewai_docs) e obter sua chave de API. + +Para rodar a plataforma Opik localmente, veja nosso [guia de instalação](https://www.comet.com/docs/opik/self-host/overview/) para mais informações. + +Neste guia, utilizaremos o exemplo de início rápido da CrewAI. + + + + ```shell + pip install crewai crewai-tools opik --upgrade + ``` + + + ```python + import opik + opik.configure(use_local=False) + ``` + + + Primeiro, configuramos nossas chaves de API do provedor LLM como variáveis de ambiente: + + ```python + import os + import getpass + + if "OPENAI_API_KEY" not in os.environ: + os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ") + ``` + + + O primeiro passo é criar nosso projeto. Vamos utilizar um exemplo da documentação do CrewAI: + + ```python + from crewai import Agent, Crew, Task, Process + + + class YourCrewName: + def agent_one(self) -> Agent: + return Agent( + role="Data Analyst", + goal="Analyze data trends in the market", + backstory="An experienced data analyst with a background in economics", + verbose=True, + ) + + def agent_two(self) -> Agent: + return Agent( + role="Market Researcher", + goal="Gather information on market dynamics", + backstory="A diligent researcher with a keen eye for detail", + verbose=True, + ) + + def task_one(self) -> Task: + return Task( + name="Collect Data Task", + description="Collect recent market data and identify trends.", + expected_output="A report summarizing key trends in the market.", + agent=self.agent_one(), + ) + + def task_two(self) -> Task: + return Task( + name="Market Research Task", + description="Research factors affecting market dynamics.", + expected_output="An analysis of factors influencing the market.", + agent=self.agent_two(), + ) + + def crew(self) -> Crew: + return Crew( + agents=[self.agent_one(), self.agent_two()], + tasks=[self.task_one(), self.task_two()], + process=Process.sequential, + verbose=True, + ) + + ``` + + Agora podemos importar o tracker do Opik e executar nossa crew: + + ```python + from opik.integrations.crewai import track_crewai + + track_crewai(project_name="crewai-integration-demo") + + my_crew = YourCrewName().crew() + result = my_crew.kickoff() + + print(result) + ``` + Após rodar sua aplicação CrewAI, acesse o app Opik para visualizar: + - Traces LLM, spans e seus metadados + - Interações dos agentes e fluxo de execução das tarefas + - Métricas de performance, como latência e uso de tokens + - Métricas de avaliação (nativas ou personalizadas) + + + +## Recursos + +- [🦉 Documentação Opik](https://www.comet.com/docs/opik/) +- [👉 Opik + CrewAI Colab](https://colab.research.google.com/github/comet-ml/opik/blob/main/apps/opik-documentation/documentation/docs/cookbook/crewai.ipynb) +- [🐦 X](https://x.com/cometml) +- [💬 Slack](https://slack.comet.com/) \ No newline at end of file diff --git a/docs/pt-BR/observability/overview.mdx b/docs/pt-BR/observability/overview.mdx new file mode 100644 index 000000000..5014af031 --- /dev/null +++ b/docs/pt-BR/observability/overview.mdx @@ -0,0 +1,118 @@ +--- +title: "Visão Geral" +description: "Monitore, avalie e otimize seus agentes CrewAI com ferramentas de observabilidade abrangentes" +icon: "face-smile" +--- + +## Observabilidade para CrewAI + +A observabilidade é fundamental para entender como seus agentes CrewAI estão desempenhando, identificar gargalos e garantir uma operação confiável em ambientes de produção. Esta seção aborda diversas ferramentas e plataformas que oferecem recursos de monitoramento, avaliação e otimização dos fluxos de trabalho dos seus agentes. + +## Por que a Observabilidade é Importante + +- **Monitoramento de Desempenho**: Acompanhe tempos de execução dos agentes, uso de tokens e consumo de recursos +- **Garantia de Qualidade**: Avalie a qualidade e a consistência das saídas em diferentes cenários +- **Depuração**: Identifique e resolva problemas no comportamento dos agentes e na execução de tarefas +- **Gestão de Custos**: Monitore o uso das APIs do LLM e os custos associados +- **Melhoria Contínua**: Colete insights para otimizar o desempenho dos agentes ao longo do tempo + +## Ferramentas de Observabilidade Disponíveis + +### Plataformas de Monitoramento e Rastreamento + + + + Replays de sessões, métricas e monitoramento para desenvolvimento e produção de agentes. + + + + Monitoramento nativo OpenTelemetry com rastreamento de custos e análises de desempenho. + + + + Gerenciamento do ciclo de vida de machine learning com rastreamento e avaliação. + + + + Plataforma de engenharia de LLM com rastreamento detalhado e análises. + + + + Observabilidade open-source para LLMs e frameworks de agentes. + + + + Plataforma de observabilidade de IA para monitoramento e solução de problemas. + + + + Gateway de IA com monitoramento abrangente e recursos de confiabilidade. + + + + Depure, avalie e monitore aplicações LLM com rastreamento abrangente. + + + + Plataforma Weights & Biases para acompanhamento e avaliação de aplicações de IA. + + + +### Avaliação & Garantia de Qualidade + + + + Plataforma abrangente de avaliação para saídas de LLM e comportamentos de agentes. + + + +## Principais Métricas de Observabilidade + +### Métricas de Desempenho +- **Tempo de Execução**: Quanto tempo os agentes levam para concluir as tarefas +- **Uso de Tokens**: Tokens de entrada/saída consumidos pelas chamadas ao LLM +- **Latência de API**: Tempo de resposta de serviços externos +- **Taxa de Sucesso**: Percentual de tarefas concluídas com sucesso + +### Métricas de Qualidade +- **Acurácia da Saída**: Correção das respostas dos agentes +- **Consistência**: Confiabilidade em entradas semelhantes +- **Relevância**: Quão bem as saídas correspondem aos resultados esperados +- **Segurança**: Conformidade com políticas de conteúdo e diretrizes + +### Métricas de Custo +- **Custos de API**: Gastos decorrentes do uso do provedor LLM +- **Utilização de Recursos**: Consumo de processamento e memória +- **Custo por Tarefa**: Eficiência econômica das operações dos agentes +- **Acompanhamento de Orçamento**: Monitoramento em relação a limites de gastos + +## Primeiros Passos + +1. **Escolha suas Ferramentas**: Selecione plataformas de observabilidade que atendam às suas necessidades +2. **Instrumente seu Código**: Adicione monitoramento às suas aplicações CrewAI +3. **Configure Dashboards**: Prepare visualizações para as métricas principais +4. **Defina Alertas**: Crie notificações para eventos importantes +5. **Estabeleça Bases de Referência**: Meça o desempenho inicial para comparação futura +6. **Itere e Melhore**: Use os insights para otimizar seus agentes + +## Boas Práticas + +### Fase de Desenvolvimento +- Utilize rastreamento detalhado para entender o comportamento dos agentes +- Implemente métricas de avaliação desde o início do desenvolvimento +- Monitore o uso de recursos durante os testes +- Estabeleça verificações automatizadas de qualidade + +### Fase de Produção +- Implemente monitoramento e alertas abrangentes +- Acompanhe tendências de desempenho ao longo do tempo +- Monitore anomalias e degradações +- Mantenha visibilidade e controle dos custos + +### Melhoria Contínua +- Revisões regulares de desempenho e otimização +- Testes A/B de diferentes configurações de agentes +- Ciclos de feedback para aprimoramento da qualidade +- Documentação de lições aprendidas + +Escolha as ferramentas de observabilidade que melhor se encaixam no seu caso de uso, infraestrutura e requisitos de monitoramento para garantir que seus agentes CrewAI operem de forma confiável e eficiente. diff --git a/docs/pt-BR/observability/patronus-evaluation.mdx b/docs/pt-BR/observability/patronus-evaluation.mdx new file mode 100644 index 000000000..83ccbd17a --- /dev/null +++ b/docs/pt-BR/observability/patronus-evaluation.mdx @@ -0,0 +1,205 @@ +--- +title: Avaliação Patronus AI +description: Monitore e avalie o desempenho de agentes CrewAI utilizando a plataforma abrangente de avaliação da Patronus AI para saídas de LLM e comportamentos de agentes. +icon: shield-check +--- + +# Avaliação Patronus AI + +## Visão Geral + +[Patronus AI](https://patronus.ai) oferece capacidades abrangentes de avaliação e monitoramento para agentes CrewAI, permitindo avaliar as saídas dos modelos, comportamentos dos agentes e o desempenho geral do sistema. Essa integração possibilita implementar fluxos de avaliação contínuos que ajudam a manter a qualidade e confiabilidade em ambientes de produção. + +## Principais Funcionalidades + +- **Avaliação Automatizada**: Avaliação em tempo real das saídas e comportamentos dos agentes +- **Critérios Personalizados**: Defina critérios de avaliação específicos para seus casos de uso +- **Monitoramento de Desempenho**: Acompanhe métricas de desempenho dos agentes ao longo do tempo +- **Garantia de Qualidade**: Assegure consistência na qualidade das saídas em diferentes cenários +- **Segurança & Conformidade**: Monitore possíveis problemas e violações de políticas + +## Ferramentas de Avaliação + +A Patronus disponibiliza três principais ferramentas de avaliação para diferentes casos de uso: + +1. **PatronusEvalTool**: Permite que os agentes selecionem o avaliador e os critérios mais apropriados para a tarefa de avaliação. +2. **PatronusPredefinedCriteriaEvalTool**: Utiliza avaliador e critérios predefinidos, especificados pelo usuário. +3. **PatronusLocalEvaluatorTool**: Utiliza avaliadores customizados definidos pelo usuário. + +## Instalação + +Para utilizar essas ferramentas, é necessário instalar o pacote Patronus: + +```shell +uv add patronus +``` + +Você também precisará configurar sua chave de API da Patronus como uma variável de ambiente: + +```shell +export PATRONUS_API_KEY="your_patronus_api_key" +``` + +## Passos para Começar + +Para utilizar as ferramentas de avaliação da Patronus de forma eficaz, siga estes passos: + +1. **Instale o Patronus**: Instale o pacote Patronus usando o comando acima. +2. **Configure a Chave de API**: Defina sua chave de API da Patronus como uma variável de ambiente. +3. **Escolha a Ferramenta Certa**: Selecione a ferramenta de avaliação Patronus mais adequada às suas necessidades. +4. **Configure a Ferramenta**: Configure a ferramenta com os parâmetros necessários. + +## Exemplos + +### Utilizando PatronusEvalTool + +O exemplo a seguir demonstra como usar o `PatronusEvalTool`, que permite aos agentes selecionar o avaliador e critérios mais apropriados: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import PatronusEvalTool + +# Initialize the tool +patronus_eval_tool = PatronusEvalTool() + +# Define an agent that uses the tool +coding_agent = Agent( + role="Coding Agent", + goal="Generate high quality code and verify that the output is code", + backstory="An experienced coder who can generate high quality python code.", + tools=[patronus_eval_tool], + verbose=True, +) + +# Example task to generate and evaluate code +generate_code_task = Task( + description="Create a simple program to generate the first N numbers in the Fibonacci sequence. Select the most appropriate evaluator and criteria for evaluating your output.", + expected_output="Program that generates the first N numbers in the Fibonacci sequence.", + agent=coding_agent, +) + +# Create and run the crew +crew = Crew(agents=[coding_agent], tasks=[generate_code_task]) +result = crew.kickoff() +``` + +### Utilizando PatronusPredefinedCriteriaEvalTool + +O exemplo a seguir demonstra como usar o `PatronusPredefinedCriteriaEvalTool`, que utiliza avaliador e critérios predefinidos: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import PatronusPredefinedCriteriaEvalTool + +# Initialize the tool with predefined criteria +patronus_eval_tool = PatronusPredefinedCriteriaEvalTool( + evaluators=[{"evaluator": "judge", "criteria": "contains-code"}] +) + +# Define an agent that uses the tool +coding_agent = Agent( + role="Coding Agent", + goal="Generate high quality code", + backstory="An experienced coder who can generate high quality python code.", + tools=[patronus_eval_tool], + verbose=True, +) + +# Example task to generate code +generate_code_task = Task( + description="Create a simple program to generate the first N numbers in the Fibonacci sequence.", + expected_output="Program that generates the first N numbers in the Fibonacci sequence.", + agent=coding_agent, +) + +# Create and run the crew +crew = Crew(agents=[coding_agent], tasks=[generate_code_task]) +result = crew.kickoff() +``` + +### Utilizando PatronusLocalEvaluatorTool + +O exemplo a seguir demonstra como usar o `PatronusLocalEvaluatorTool`, que utiliza avaliadores customizados via função: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import PatronusLocalEvaluatorTool +from patronus import Client, EvaluationResult +import random + +# Initialize the Patronus client +client = Client() + +# Register a custom evaluator +@client.register_local_evaluator("random_evaluator") +def random_evaluator(**kwargs): + score = random.random() + return EvaluationResult( + score_raw=score, + pass_=score >= 0.5, + explanation="example explanation", + ) + +# Initialize the tool with the custom evaluator +patronus_eval_tool = PatronusLocalEvaluatorTool( + patronus_client=client, + evaluator="random_evaluator", + evaluated_model_gold_answer="example label", +) + +# Define an agent that uses the tool +coding_agent = Agent( + role="Coding Agent", + goal="Generate high quality code", + backstory="An experienced coder who can generate high quality python code.", + tools=[patronus_eval_tool], + verbose=True, +) + +# Example task to generate code +generate_code_task = Task( + description="Create a simple program to generate the first N numbers in the Fibonacci sequence.", + expected_output="Program that generates the first N numbers in the Fibonacci sequence.", + agent=coding_agent, +) + +# Create and run the crew +crew = Crew(agents=[coding_agent], tasks=[generate_code_task]) +result = crew.kickoff() +``` + +## Parâmetros + +### PatronusEvalTool + +O `PatronusEvalTool` não exige parâmetros durante a inicialização. Ele busca automaticamente os avaliadores e critérios disponíveis a partir da API da Patronus. + +### PatronusPredefinedCriteriaEvalTool + +O `PatronusPredefinedCriteriaEvalTool` aceita os seguintes parâmetros durante a inicialização: + +- **evaluators**: Obrigatório. Uma lista de dicionários contendo o avaliador e os critérios a serem utilizados. Por exemplo: `[{"evaluator": "judge", "criteria": "contains-code"}]`. + +### PatronusLocalEvaluatorTool + +O `PatronusLocalEvaluatorTool` aceita os seguintes parâmetros durante a inicialização: + +- **patronus_client**: Obrigatório. Instância do cliente Patronus. +- **evaluator**: Opcional. O nome do avaliador local registrado a ser utilizado. Default é uma string vazia. +- **evaluated_model_gold_answer**: Opcional. A resposta padrão (“gold answer”) para uso na avaliação. O padrão é uma string vazia. + +## Uso + +Ao utilizar as ferramentas de avaliação Patronus, você fornece a entrada do modelo, a saída e o contexto, e a ferramenta retorna os resultados da avaliação a partir da API da Patronus. + +Para o `PatronusEvalTool` e o `PatronusPredefinedCriteriaEvalTool`, os seguintes parâmetros são obrigatórios ao chamar a ferramenta: + +- **evaluated_model_input**: A descrição da tarefa do agente, em texto simples. +- **evaluated_model_output**: A saída da tarefa pelo agente. +- **evaluated_model_retrieved_context**: O contexto do agente. + +Para o `PatronusLocalEvaluatorTool`, os mesmos parâmetros são necessários, mas o avaliador e a resposta padrão são especificados durante a inicialização. + +## Conclusão + +As ferramentas de avaliação da Patronus fornecem uma forma poderosa de avaliar e pontuar entradas e saídas de modelos utilizando a plataforma Patronus AI. Ao possibilitar que agentes avaliem suas próprias saídas ou as de outros agentes, essas ferramentas ajudam a aprimorar a qualidade e confiabilidade dos fluxos de trabalho do CrewAI. \ No newline at end of file diff --git a/docs/pt-BR/observability/portkey.mdx b/docs/pt-BR/observability/portkey.mdx new file mode 100644 index 000000000..6e45bf9d8 --- /dev/null +++ b/docs/pt-BR/observability/portkey.mdx @@ -0,0 +1,824 @@ +--- +title: Integração com Portkey +description: Como usar Portkey com CrewAI +icon: key +--- + +Portkey CrewAI Header Image + + + +## Introdução + +Portkey aprimora o CrewAI com recursos prontos para produção, transformando seus crews de agentes experimentais em sistemas robustos ao fornecer: + +- **Observabilidade completa** de cada etapa do agente, uso de ferramentas e interações +- **Confiabilidade incorporada** com fallbacks, tentativas automáticas e balanceamento de carga +- **Rastreamento e otimização de custos** para gerenciar seus gastos com IA +- **Acesso a mais de 200 LLMs** por meio de uma única integração +- **Guardrails** para manter o comportamento dos agentes seguro e em conformidade +- **Prompts versionados** para desempenho consistente dos agentes + + +### Instalação & Configuração + + + +```bash +pip install -U crewai portkey-ai +``` + + + +Crie uma chave de API Portkey com limites de orçamento/taxa opcionais no [painel da Portkey](https://app.portkey.ai/). Você também pode adicionar configurações para confiabilidade, cache e outros recursos a essa chave. Mais sobre isso em breve. + + + +A integração é simples – basta atualizar a configuração do LLM no seu setup do CrewAI: + +```python +from crewai import LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Crie uma instância do LLM com integração Portkey +gpt_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", # Estamos usando uma chave virtual, então isso é apenas um placeholder + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_LLM_VIRTUAL_KEY", + trace_id="unique-trace-id", # Opcional, para rastreamento da requisição + ) +) + +#Use-os nos seus Crew Agents assim: + + @agent + def lead_market_analyst(self) -> Agent: + return Agent( + config=self.agents_config['lead_market_analyst'], + verbose=True, + memory=False, + llm=gpt_llm + ) + +``` + + +**O que são Virtual Keys?** Virtual keys no Portkey armazenam com segurança suas chaves de API dos provedores LLM (OpenAI, Anthropic, etc.) em um cofre criptografado. Elas facilitam a rotação de chaves e o gerenciamento de orçamento. [Saiba mais sobre virtual keys aqui](https://portkey.ai/docs/product/ai-gateway/virtual-keys). + + + + +## Recursos para Produção + +### 1. Observabilidade Avançada + +Portkey oferece observabilidade abrangente para seus agentes CrewAI, ajudando você a entender exatamente o que está acontecendo durante cada execução. + + + + + + + +Os traces fornecem uma visão hierárquica da execução do seu crew, mostrando a sequência de chamadas LLM, ativações de ferramentas e transições de estado. + +```python +# Adicione trace_id para habilitar o tracing hierárquico no Portkey +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY", + trace_id="unique-session-id" # Adicione um trace ID único + ) +) +``` + + + + + + + +Portkey registra cada interação com LLMs, incluindo: + +- Payloads completos das requisições e respostas +- Métricas de latência e uso de tokens +- Cálculos de custo +- Chamadas de ferramentas e execuções de funções + +Todos os logs podem ser filtrados por metadados, trace IDs, modelos e mais, tornando mais fácil depurar execuções específicas do crew. + + + + + + + +Portkey oferece dashboards integrados que ajudam você a: + +- Rastrear custos e uso de tokens em todas as execuções do crew +- Analisar métricas de desempenho, como latência e taxas de sucesso +- Identificar gargalos nos fluxos de trabalho dos agentes +- Comparar diferentes configurações de crew e LLMs + +Você pode filtrar e segmentar todas as métricas por metadados personalizados para analisar tipos de crew, grupos de usuários ou casos de uso específicos. + + + + + Analytics with metadata filters + + +Adicione metadados personalizados à configuração LLM do seu CrewAI para permitir filtragem e segmentação poderosas: + +```python +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY", + metadata={ + "crew_type": "research_crew", + "environment": "production", + "_user": "user_123", # Campo especial _user para analytics de usuários + "request_source": "mobile_app" + } + ) +) +``` + +Esses metadados podem ser usados para filtrar logs, traces e métricas no painel do Portkey, permitindo analisar execuções específicas do crew, usuários ou ambientes. + + + +### 2. Confiabilidade - Mantenha Seus Crews Funcionando Sem Interrupções + +Ao executar crews em produção, problemas podem ocorrer – limites de taxa da API, problemas de rede ou indisponibilidade do provedor. Os recursos de confiabilidade do Portkey garantem que seus agentes continuem funcionando mesmo quando problemas surgem. + +É simples habilitar fallback na sua configuração CrewAI usando um Config do Portkey: + +```python +from crewai import LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Crie LLM com configuração de fallback +portkey_llm = LLM( + model="gpt-4o", + max_tokens=1000, + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + config={ + "strategy": { + "mode": "fallback" + }, + "targets": [ + { + "provider": "openai", + "api_key": "YOUR_OPENAI_API_KEY", + "override_params": {"model": "gpt-4o"} + }, + { + "provider": "anthropic", + "api_key": "YOUR_ANTHROPIC_API_KEY", + "override_params": {"model": "claude-3-opus-20240229"} + } + ] + } + ) +) + +# Use essa configuração LLM com seus agentes +``` + +Essa configuração automaticamente tentará o Claude caso a requisição para o GPT-4o falhe, garantindo que seu crew continue funcionando. + + + + Lida automaticamente com falhas temporárias. Se uma chamada LLM falhar, o Portkey fará novas tentativas o número especificado de vezes – perfeito para limites de taxa ou instabilidades de rede. + + + Evite que seus agentes fiquem travados. Defina timeouts para garantir respostas (ou falhas controladas) dentro do tempo necessário. + + + Envie diferentes solicitações para diferentes provedores. Direcione raciocínios complexos para o GPT-4, tarefas criativas para Claude e respostas rápidas para Gemini conforme sua necessidade. + + + Mantenha-se em funcionamento mesmo se seu provedor principal falhar. Troque automaticamente para provedores de backup para manter a disponibilidade. + + + Distribua solicitações entre várias chaves de API ou provedores. Ótimo para operações de crew em grande escala e para permanecer dentro dos limites de taxa. + + + +### 3. Prompting no CrewAI + +O Prompt Engineering Studio do Portkey ajuda você a criar, gerenciar e otimizar os prompts usados em seus agentes CrewAI. Em vez de codificar prompts ou instruções manualmente, use a API de renderização de prompts do Portkey para buscar e aplicar dinâmicamente seus prompts versionados. + + +![Prompt Playground Interface](https://raw.githubusercontent.com/siddharthsambharia-portkey/Portkey-Product-Images/refs/heads/main/CrewAI%20Portkey%20Docs.webp) + + + + +Prompt Playground é um local para comparar, testar e implantar prompts perfeitos para sua aplicação de IA. É onde você experimenta com diferentes modelos, testa variáveis, compara saídas e refina sua estratégia de engenharia de prompts antes de implantar em produção. Ele permite: + +1. Desenvolver prompts de forma iterativa antes de usá-los em seus agentes +2. Testar prompts com diferentes variáveis e modelos +3. Comparar saídas entre diferentes versões de prompts +4. Colaborar com membros da equipe no desenvolvimento de prompts + +Esse ambiente visual facilita a criação de prompts eficazes para cada etapa do fluxo de trabalho dos seus agentes CrewAI. + + + +A API Prompt Render recupera seus templates de prompt com todos os parâmetros configurados: + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL, Portkey + +# Inicialize o cliente admin do Portkey +portkey_admin = Portkey(api_key="YOUR_PORTKEY_API_KEY") + +# Recupere o prompt usando a render API +prompt_data = portkey_client.prompts.render( + prompt_id="YOUR_PROMPT_ID", + variables={ + "agent_role": "Senior Research Scientist", + } +) + +backstory_agent_prompt=prompt_data.data.messages[0]["content"] + + +# Configure o LLM com integração Portkey +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY" + ) +) + +# Crie o agente utilizando o prompt renderizado +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory=backstory_agent, # Use o prompt renderizado + verbose=True, + llm=portkey_llm +) +``` + + + +Você pode: +- Criar múltiplas versões do mesmo prompt +- Comparar o desempenho entre versões +- Voltar a versões anteriores se necessário +- Especificar qual versão usar em seu código: + +```python +# Use uma versão específica do prompt +prompt_data = portkey_admin.prompts.render( + prompt_id="YOUR_PROMPT_ID@version_number", + variables={ + "agent_role": "Senior Research Scientist", + "agent_goal": "Discover groundbreaking insights" + } +) +``` + + + +Os prompts do Portkey usam modelos estilo Mustache para fácil substituição de variáveis: + +``` +You are a {{agent_role}} with expertise in {{domain}}. + +Your mission is to {{agent_goal}} by leveraging your knowledge +and experience in the field. + +Always maintain a {{tone}} tone and focus on providing {{focus_area}}. +``` + +Ao renderizar, basta passar as variáveis: + +```python +prompt_data = portkey_admin.prompts.render( + prompt_id="YOUR_PROMPT_ID", + variables={ + "agent_role": "Senior Research Scientist", + "domain": "artificial intelligence", + "agent_goal": "discover groundbreaking insights", + "tone": "professional", + "focus_area": "practical applications" + } +) +``` + + + + + Saiba mais sobre os recursos de gerenciamento de prompts do Portkey + + +### 4. Guardrails para Crews Seguros + +Guardrails garantem que seus agentes CrewAI operem com segurança e respondam adequadamente em todas as situações. + +**Por que usar Guardrails?** + +Os agentes CrewAI podem apresentar falhas de diversos tipos: +- Gerar conteúdo nocivo ou inapropriado +- Vazamento de informações sensíveis como PII +- Alucinar informações incorretas +- Gerar saídas em formatos incorretos + +Os guardrails do Portkey fornecem proteções tanto para entradas quanto para saídas. + +**Implementando Guardrails** + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Crie LLM com guardrails +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY", + config={ + "input_guardrails": ["guardrails-id-xxx", "guardrails-id-yyy"], + "output_guardrails": ["guardrails-id-zzz"] + } + ) +) + +# Crie agente com LLM guardrailed +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory="You are an expert researcher with deep domain knowledge.", + verbose=True, + llm=portkey_llm +) +``` + +Os guardrails do Portkey podem: +- Detectar e redigir PII tanto em entradas quanto em saídas +- Filtrar conteúdo prejudicial ou inapropriado +- Validar formatos de resposta contra schemas +- Verificar alucinações comparando com ground truth +- Aplicar lógica e regras de negócio personalizadas + + + Explore os recursos de guardrails do Portkey para aumentar a segurança dos agentes + + +### 5. Rastreamento de Usuário com Metadados + +Rastreie usuários individuais através dos seus agentes CrewAI utilizando o sistema de metadados do Portkey. + +**O que é Metadata no Portkey?** + +Metadados permitem associar dados personalizados a cada requisição, possibilitando filtragem, segmentação e analytics. O campo especial `_user` é projetado especificamente para rastreamento de usuário. + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure o LLM com rastreamento de usuário +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY", + metadata={ + "_user": "user_123", # Campo especial _user para analytics de usuários + "user_tier": "premium", + "user_company": "Acme Corp", + "session_id": "abc-123" + } + ) +) + +# Crie agente com LLM rastreado +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory="You are an expert researcher with deep domain knowledge.", + verbose=True, + llm=portkey_llm +) +``` + +**Filtre Analytics por Usuário** + +Com os metadados configurados, você pode filtrar analytics por usuário e analisar métricas de desempenho individualmente: + + + + + +Isso permite: +- Rastreamento de custos e orçamento por usuário +- Analytics personalizados por usuário +- Métricas por equipe ou organização +- Monitoramento específico por ambiente (homologação x produção) + + + Veja como usar metadados personalizados para aprimorar seus analytics + + +### 6. Cache para Crews Eficientes + +Implemente caching para tornar seus agentes CrewAI mais eficientes e econômicos: + + + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure o LLM com caching simples +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY", + config={ + "cache": { + "mode": "simple" + } + } + ) +) + +# Crie agente com LLM cacheado +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory="You are an expert researcher with deep domain knowledge.", + verbose=True, + llm=portkey_llm +) +``` + +O caching simples realiza correspondências exatas de prompts de entrada, cacheando requisições idênticas para evitar execuções redundantes do modelo. + + + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure o LLM com cache semântico +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY", + config={ + "cache": { + "mode": "semantic" + } + } + ) +) + +# Crie agente com LLM com cache semântico +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory="You are an expert researcher with deep domain knowledge.", + verbose=True, + llm=portkey_llm +) +``` + +O cache semântico considera a similaridade contextual entre solicitações de entrada, armazenando respostas para entradas semanticamente similares. + + + +### 7. Interoperabilidade de Modelos + +O CrewAI oferece suporte a múltiplos provedores de LLM, e o Portkey amplia essa capacidade fornecendo acesso a mais de 200 LLMs por meio de uma interface unificada. Você pode facilmente alternar entre diferentes modelos sem alterar a lógica central do seu agente: + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure LLMs com diferentes provedores +openai_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY" + ) +) + +anthropic_llm = LLM( + model="claude-3-5-sonnet-latest", + max_tokens=1000, + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_ANTHROPIC_VIRTUAL_KEY" + ) +) + +# Escolha qual LLM usar para cada agente conforme necessário +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory="You are an expert researcher with deep domain knowledge.", + verbose=True, + llm=openai_llm # Use anthropic_llm para Anthropic +) +``` + +Portkey oferece acesso a LLMs de provedores como: + +- OpenAI (GPT-4o, GPT-4 Turbo, etc.) +- Anthropic (Claude 3.5 Sonnet, Claude 3 Opus, etc.) +- Mistral AI (Mistral Large, Mistral Medium, etc.) +- Google Vertex AI (Gemini 1.5 Pro, etc.) +- Cohere (Command, Command-R, etc.) +- AWS Bedrock (Claude, Titan, etc.) +- Modelos locais/privados + + + Veja a lista completa de provedores LLM suportados pelo Portkey + + +## Configure Governança Corporativa para o CrewAI + +**Por que Governança Corporativa?** +Se você utiliza CrewAI dentro de sua organização, é importante considerar diversos aspectos de governança: +- **Gestão de Custos**: Controlar e rastrear os gastos com IA entre equipes +- **Controle de Acesso**: Gerenciar quais equipes podem usar modelos específicos +- **Analytics de Uso**: Compreender como a IA está sendo utilizada na organização +- **Segurança & Compliance**: Manutenção de padrões corporativos de segurança +- **Confiabilidade**: Garantir serviço consistente para todos os usuários + +O Portkey adiciona uma camada abrangente de governança para atender a essas necessidades corporativas. Vamos implementar esses controles passo a passo. + + + +Virtual Keys são a maneira segura do Portkey para gerenciar as chaves de API dos provedores de LLM. Elas fornecem controles essenciais como: +- Limites de orçamento para uso da API +- Capacidade de rate limiting +- Armazenamento seguro das chaves de API + +Para criar uma virtual key: +Vá até [Virtual Keys](https://app.portkey.ai/virtual-keys) no app Portkey. Salve e copie o ID da virtual key + + + + + + +Salve o ID da sua virtual key – você precisará dele no próximo passo. + + + + +Os Configs no Portkey definem como suas requisições são roteadas, com recursos como roteamento avançado, fallbacks e tentativas automáticas. + +Para criar seu config: +1. Vá até [Configs](https://app.portkey.ai/configs) no painel Portkey +2. Crie um novo config com: + ```json + { + "virtual_key": "YOUR_VIRTUAL_KEY_FROM_STEP1", + "override_params": { + "model": "gpt-4o" // Nome do seu modelo preferido + } + } + ``` +3. Salve e anote o nome do Config para o próximo passo + + + + + + + + +Agora crie uma chave de API Portkey e anexe a config criada no Passo 2: + +1. Vá até [API Keys](https://app.portkey.ai/api-keys) na Portkey e crie uma nova chave de API +2. Selecione sua config do `Passo 2` +3. Gere e salve sua chave de API + + + + + + + + +Após configurar sua chave de API Portkey com a config anexada, conecte-a aos seus agentes CrewAI: + +```python +from crewai import Agent, LLM +from portkey_ai import PORTKEY_GATEWAY_URL + +# Configure o LLM com sua chave de API +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="YOUR_PORTKEY_API_KEY" +) + +# Crie agente com LLM habilitado para Portkey +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory="You are an expert researcher with deep domain knowledge.", + verbose=True, + llm=portkey_llm +) +``` + + + + + +### Etapa 1: Implementar Controles de Orçamento & Rate Limits + +Virtual Keys permitem controle granular sobre o acesso ao LLM por equipe/departamento. Isso ajuda você a: +- Definir [limites de orçamento](https://portkey.ai/docs/product/ai-gateway/virtual-keys/budget-limits) +- Prevenir picos inesperados de uso através de Rate limits +- Rastrear gastos por departamento + +#### Configurando controles específicos de departamento: +1. Vá até [Virtual Keys](https://app.portkey.ai/virtual-keys) no painel Portkey +2. Crie uma nova Virtual Key para cada departamento com limites de orçamento e rate limits +3. Configure limites específicos por departamento + + + + + + + +### Etapa 2: Definir Regras de Acesso a Modelos + +À medida que o uso de IA cresce, controlar quais equipes têm acesso a quais modelos se torna fundamental. Os Configs do Portkey fornecem essa camada de controle com recursos como: + +#### Recursos de Controle de Acesso: +- **Restrições de Modelo**: Limite o acesso a modelos específicos +- **Proteção de Dados**: Implemente guardrails para dados sensíveis +- **Controles de Confiabilidade**: Adicione fallbacks e tentativas automáticas + +#### Exemplo de Configuração: +Aqui está um exemplo básico para rotear requisições ao OpenAI, usando especificamente o GPT-4o: + +```json +{ + "strategy": { + "mode": "single" + }, + "targets": [ + { + "virtual_key": "YOUR_OPENAI_VIRTUAL_KEY", + "override_params": { + "model": "gpt-4o" + } + } + ] +} +``` + + Crie seu config na [página de Configs](https://app.portkey.ai/configs) no painel do Portkey. + + + Os configs podem ser atualizados a qualquer momento para ajustar controles sem afetar aplicações em execução. + + + + + ### Etapa 3: Implementar Controles de Acesso + + Crie chaves de API específicas por usuário que automaticamente: + - Rastreiam uso por usuário/equipe com o auxílio das virtual keys + - Aplicam configs adequadas para rotear requisições + - Coletam metadados relevantes para filtragem de logs + - Impõem permissões de acesso + + Crie chaves de API através de: + - [Portkey App](https://app.portkey.ai/) + - [API Key Management API](/pt-BR/api-reference/admin-api/control-plane/api-keys/create-api-key) + + Exemplo usando Python SDK: + ```python + from portkey_ai import Portkey + + portkey = Portkey(api_key="YOUR_ADMIN_API_KEY") + + api_key = portkey.api_keys.create( + name="engineering-team", + type="organisation", + workspace_id="YOUR_WORKSPACE_ID", + defaults={ + "config_id": "your-config-id", + "metadata": { + "environment": "production", + "department": "engineering" + } + }, + scopes=["logs.view", "configs.read"] + ) + ``` + + Para instruções detalhadas de gerenciamento de chaves, veja nossa [documentação de API Keys](/pt-BR/api-reference/admin-api/control-plane/api-keys/create-api-key). + + + + ### Etapa 4: Implante & Monitore + Após distribuir as chaves de API para os membros da equipe, seu setup corporativo CrewAI está pronto. Cada membro pode agora usar suas chaves designadas com os níveis de acesso e controles de orçamento apropriados. + + Monitore o uso no painel Portkey: + - Rastreamento de custos por departamento + - Padrões de uso de modelos + - Volume de requisições + - Taxa de erros + + + + + +### Recursos Corporativos Agora Disponíveis +**Sua integração CrewAI agora conta com:** +- Controles de orçamento departamental +- Governança de acesso a modelos +- Rastreamento de uso & atribuição +- Guardrails de segurança +- Recursos de confiabilidade + + +## Perguntas Frequentes + + + + Portkey adiciona prontidão para produção ao CrewAI através de observabilidade abrangente (traces, logs, métricas), recursos de confiabilidade (fallbacks, tentativas automáticas, cache) e acesso a mais de 200 LLMs por meio de uma interface unificada. Isso facilita depurar, otimizar e escalar suas aplicações de agentes. + + + + Sim! Portkey integra-se perfeitamente a aplicações CrewAI existentes. Basta atualizar o código de configuração do LLM com a versão habilitada do Portkey. O restante do seu código de agente e crew permanece inalterado. + + + + Portkey suporta todos os recursos do CrewAI, incluindo agentes, ferramentas, workflows human-in-the-loop e todos os tipos de processo de tarefas (sequencial, hierárquico, etc.). Ele adiciona observabilidade e confiabilidade sem limitar nenhuma funcionalidade do framework. + + + + Sim, o Portkey permite que você use um `trace_id` consistente em múltiplos agentes de um crew para rastrear todo o fluxo de trabalho. Isso é especialmente útil para crews complexos onde você deseja entender o caminho completo de execução entre os agentes. + + + + O Portkey permite adicionar metadados personalizados à configuração do seu LLM, que podem ser usados para filtragem. Adicione campos como `crew_name`, `crew_type`, ou `session_id` para encontrar e analisar facilmente execuções específicas do crew. + + + + Sim! O Portkey utiliza suas próprias chaves de API dos provedores LLM. Elas são armazenadas com segurança como virtual keys, permitindo que você gerencie e gire as chaves facilmente sem alterar seu código. + + + + +## Recursos + + + +

Documentação oficial do CrewAI

+
+ +

Receba orientação personalizada sobre como implementar essa integração

+
+
diff --git a/docs/pt-BR/observability/weave.mdx b/docs/pt-BR/observability/weave.mdx new file mode 100644 index 000000000..43dbeb370 --- /dev/null +++ b/docs/pt-BR/observability/weave.mdx @@ -0,0 +1,124 @@ +--- +title: Integração com Weave +description: Saiba como usar o Weights & Biases (W&B) Weave para rastrear, experimentar, avaliar e melhorar suas aplicações CrewAI. +icon: radar +--- + +# Visão Geral do Weave + +[Weights & Biases (W&B) Weave](https://weave-docs.wandb.ai/) é um framework para rastreamento, experimentação, avaliação, implementação e aprimoramento de aplicações baseadas em LLM. + +![Visão geral do uso do tracing do W&B Weave com CrewAI](/images/weave-tracing.gif) + +O Weave oferece suporte completo para todas as etapas do desenvolvimento da sua aplicação CrewAI: + +- **Rastreamento e Monitoramento**: Acompanhe automaticamente chamadas LLM e a lógica da aplicação para depuração e análise de sistemas em produção +- **Iteração Sistemática**: Aperfeiçoe e itere em prompts, conjuntos de dados e modelos +- **Avaliação**: Utilize avaliadores personalizados ou pré-construídos para avaliar e aprimorar sistematicamente o desempenho dos agentes +- **Guardrails**: Proteja seus agentes com salvaguardas pré e pós-execução para moderação de conteúdo e segurança de prompts + +O Weave captura automaticamente rastreamentos (traces) de suas aplicações CrewAI, permitindo monitorar e analisar o desempenho, as interações e o fluxo de execução dos seus agentes. Isso te ajuda a construir melhores conjuntos de dados para avaliação e a otimizar os fluxos de trabalho dos agentes. + +## Instruções de Configuração + + + + ```shell + pip install crewai weave + ``` + + + Cadastre-se em uma [conta Weights & Biases](https://wandb.ai) caso ainda não tenha uma. Você precisará dela para visualizar rastreamentos e métricas. + + + Adicione o seguinte código à sua aplicação: + + ```python + import weave + + # Inicialize o Weave com o nome do seu projeto + weave.init(project_name="crewai_demo") + ``` + + Após a inicialização, o Weave fornecerá uma URL onde você poderá visualizar seus rastreamentos e métricas. + + + ```python + from crewai import Agent, Task, Crew, LLM, Process + + # Crie um LLM com temperatura 0 para garantir saídas determinísticas + llm = LLM(model="gpt-4o", temperature=0) + + # Crie os agentes + researcher = Agent( + role='Research Analyst', + goal='Find and analyze the best investment opportunities', + backstory='Expert in financial analysis and market research', + llm=llm, + verbose=True, + allow_delegation=False, + ) + + writer = Agent( + role='Report Writer', + goal='Write clear and concise investment reports', + backstory='Experienced in creating detailed financial reports', + llm=llm, + verbose=True, + allow_delegation=False, + ) + + # Crie as tarefas + research_task = Task( + description='Deep research on the {topic}', + expected_output='Comprehensive market data including key players, market size, and growth trends.', + agent=researcher + ) + + writing_task = Task( + description='Write a detailed report based on the research', + expected_output='The report should be easy to read and understand. Use bullet points where applicable.', + agent=writer + ) + + # Crie o crew + crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True, + process=Process.sequential, + ) + + # Execute o crew + result = crew.kickoff(inputs={"topic": "AI in material science"}) + print(result) + ``` + + + Após executar sua aplicação CrewAI, acesse a URL do Weave fornecida durante a inicialização para visualizar: + - Chamadas LLM e seus metadados + - Interações dos agentes e fluxo de execução das tarefas + - Métricas de desempenho como latência e uso de tokens + - Quaisquer erros ou problemas ocorridos durante a execução + + + Exemplo de rastreamento do Weave com CrewAI + + + + +## Funcionalidades + +- O Weave captura automaticamente todas as operações do CrewAI: interações dos agentes e execuções das tarefas; chamadas LLM com metadados e uso de tokens; uso de ferramentas e resultados. +- A integração suporta todos os métodos de execução do CrewAI: `kickoff()`, `kickoff_for_each()`, `kickoff_async()` e `kickoff_for_each_async()`. +- Rastreamento automático de todas as [crewAI-tools](https://github.com/crewAIInc/crewAI-tools). +- Suporte ao recurso flow com patching por decorador (`@start`, `@listen`, `@router`, `@or_`, `@and_`). +- Rastreie guardrails personalizados passados para o `Task` do CrewAI com `@weave.op()`. + +Para informações detalhadas sobre o que é suportado, acesse a [documentação do Weave CrewAI](https://weave-docs.wandb.ai/guides/integrations/crewai/#getting-started-with-flow). + +## Recursos + +- [📘 Documentação do Weave](https://weave-docs.wandb.ai) +- [📊 Exemplo de dashboard Weave x CrewAI](https://wandb.ai/ayut/crewai_demo/weave/traces?cols=%7B%22wb_run_id%22%3Afalse%2C%22attributes.weave.client_version%22%3Afalse%2C%22attributes.weave.os_name%22%3Afalse%2C%22attributes.weave.os_release%22%3Afalse%2C%22attributes.weave.os_version%22%3Afalse%2C%22attributes.weave.source%22%3Afalse%2C%22attributes.weave.sys_version%22%3Afalse%7D&peekPath=%2Fayut%2Fcrewai_demo%2Fcalls%2F0195c838-38cb-71a2-8a15-651ecddf9d89) +- [🐦 X](https://x.com/weave_wb) \ No newline at end of file diff --git a/docs/pt-BR/quickstart.mdx b/docs/pt-BR/quickstart.mdx new file mode 100644 index 000000000..715369ef5 --- /dev/null +++ b/docs/pt-BR/quickstart.mdx @@ -0,0 +1,372 @@ +--- +title: Guia Rápido +description: Construa seu primeiro agente de IA com a CrewAI em menos de 5 minutos. +icon: rocket +--- + +## Construa seu primeiro Agente CrewAI + +Vamos criar uma tripulação simples que nos ajudará a `pesquisar` e `relatar` sobre os `últimos avanços em IA` para um determinado tópico ou assunto. + +Antes de prosseguir, certifique-se de ter concluído a instalação da CrewAI. +Se ainda não instalou, faça isso seguindo o [guia de instalação](/pt-BR/installation). + +Siga os passos abaixo para começar a tripular! 🚣‍♂️ + + + + Crie um novo projeto de tripulação executando o comando abaixo em seu terminal. + Isso criará um novo diretório chamado `latest-ai-development` com a estrutura básica para sua tripulação. + + ```shell Terminal + crewai create crew latest-ai-development + ``` + + + + + ```shell Terminal + cd latest-ai-development + ``` + + + + + Você também pode modificar os agentes conforme necessário para atender ao seu caso de uso ou copiar e colar como está para seu projeto. + Qualquer variável interpolada nos seus arquivos `agents.yaml` e `tasks.yaml`, como `{topic}`, será substituída pelo valor da variável no arquivo `main.py`. + + ```yaml agents.yaml + # src/latest_ai_development/config/agents.yaml + researcher: + role: > + {topic} Senior Data Researcher + goal: > + Uncover cutting-edge developments in {topic} + backstory: > + You're a seasoned researcher with a knack for uncovering the latest + developments in {topic}. Known for your ability to find the most relevant + information and present it in a clear and concise manner. + + reporting_analyst: + role: > + {topic} Reporting Analyst + goal: > + Create detailed reports based on {topic} data analysis and research findings + backstory: > + You're a meticulous analyst with a keen eye for detail. You're known for + your ability to turn complex data into clear and concise reports, making + it easy for others to understand and act on the information you provide. + ``` + + + ```yaml tasks.yaml + # src/latest_ai_development/config/tasks.yaml + research_task: + description: > + Conduct a thorough research about {topic} + Make sure you find any interesting and relevant information given + the current year is 2025. + expected_output: > + A list with 10 bullet points of the most relevant information about {topic} + agent: researcher + + reporting_task: + description: > + Review the context you got and expand each topic into a full section for a report. + Make sure the report is detailed and contains any and all relevant information. + expected_output: > + A fully fledge reports with the mains topics, each with a full section of information. + Formatted as markdown without '```' + agent: reporting_analyst + output_file: report.md + ``` + + + ```python crew.py + # src/latest_ai_development/crew.py + from crewai import Agent, Crew, Process, Task + from crewai.project import CrewBase, agent, crew, task + from crewai_tools import SerperDevTool + from crewai.agents.agent_builder.base_agent import BaseAgent + from typing import List + + @CrewBase + class LatestAiDevelopmentCrew(): + """LatestAiDevelopment crew""" + + agents: List[BaseAgent] + tasks: List[Task] + + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], # type: ignore[index] + verbose=True, + tools=[SerperDevTool()] + ) + + @agent + def reporting_analyst(self) -> Agent: + return Agent( + config=self.agents_config['reporting_analyst'], # type: ignore[index] + verbose=True + ) + + @task + def research_task(self) -> Task: + return Task( + config=self.tasks_config['research_task'], # type: ignore[index] + ) + + @task + def reporting_task(self) -> Task: + return Task( + config=self.tasks_config['reporting_task'], # type: ignore[index] + output_file='output/report.md' # This is the file that will be contain the final report. + ) + + @crew + def crew(self) -> Crew: + """Creates the LatestAiDevelopment crew""" + return Crew( + agents=self.agents, # Automatically created by the @agent decorator + tasks=self.tasks, # Automatically created by the @task decorator + process=Process.sequential, + verbose=True, + ) + ``` + + + ```python crew.py + # src/latest_ai_development/crew.py + from crewai import Agent, Crew, Process, Task + from crewai.project import CrewBase, agent, crew, task, before_kickoff, after_kickoff + from crewai_tools import SerperDevTool + + @CrewBase + class LatestAiDevelopmentCrew(): + """LatestAiDevelopment crew""" + + @before_kickoff + def before_kickoff_function(self, inputs): + print(f"Before kickoff function with inputs: {inputs}") + return inputs # You can return the inputs or modify them as needed + + @after_kickoff + def after_kickoff_function(self, result): + print(f"After kickoff function with result: {result}") + return result # You can return the result or modify it as needed + + # ... remaining code + ``` + + + Por exemplo, você pode passar o input `topic` para sua tripulação para personalizar a pesquisa e o relatório. + ```python main.py + #!/usr/bin/env python + # src/latest_ai_development/main.py + import sys + from latest_ai_development.crew import LatestAiDevelopmentCrew + + def run(): + """ + Run the crew. + """ + inputs = { + 'topic': 'AI Agents' + } + LatestAiDevelopmentCrew().crew().kickoff(inputs=inputs) + ``` + + + Antes de executar sua tripulação, certifique-se de ter as seguintes chaves configuradas como variáveis de ambiente no seu arquivo `.env`: + - Uma chave da API do [Serper.dev](https://serper.dev/): `SERPER_API_KEY=YOUR_KEY_HERE` + - A configuração do modelo de sua escolha, como uma chave de API. Veja o + [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm) para aprender como configurar modelos de qualquer provedor. + + + - Trave e instale as dependências utilizando o comando da CLI: + + ```shell Terminal + crewai install + ``` + + - Se quiser instalar pacotes adicionais, faça isso executando: + + ```shell Terminal + uv add + ``` + + + + - Para executar sua tripulação, rode o seguinte comando na raiz do projeto: + + ```bash Terminal + crewai run + ``` + + + + + Para usuários do CrewAI Enterprise, você pode criar a mesma tripulação sem escrever código: + + 1. Faça login na sua conta CrewAI Enterprise (crie uma conta gratuita em [app.crewai.com](https://app.crewai.com)) + 2. Abra o Crew Studio + 3. Digite qual automação deseja construir + 4. Crie suas tarefas visualmente e conecte-as em sequência + 5. Configure seus inputs e clique em "Download Code" ou "Deploy" + + ![Crew Studio Quickstart](/images/enterprise/crew-studio-interface.png) + + + Comece sua conta gratuita no CrewAI Enterprise + + + + Você verá a saída no console e o arquivo `report.md` deve ser criado na raiz do seu projeto com o relatório final. + + Veja um exemplo de como o relatório deve ser: + + + ```markdown output/report.md + # Comprehensive Report on the Rise and Impact of AI Agents in 2025 + + ## 1. Introduction to AI Agents + In 2025, Artificial Intelligence (AI) agents are at the forefront of innovation across various industries. As intelligent systems that can perform tasks typically requiring human cognition, AI agents are paving the way for significant advancements in operational efficiency, decision-making, and overall productivity within sectors like Human Resources (HR) and Finance. This report aims to detail the rise of AI agents, their frameworks, applications, and potential implications on the workforce. + + ## 2. Benefits of AI Agents + AI agents bring numerous advantages that are transforming traditional work environments. Key benefits include: + + - **Task Automation**: AI agents can carry out repetitive tasks such as data entry, scheduling, and payroll processing without human intervention, greatly reducing the time and resources spent on these activities. + - **Improved Efficiency**: By quickly processing large datasets and performing analyses that would take humans significantly longer, AI agents enhance operational efficiency. This allows teams to focus on strategic tasks that require higher-level thinking. + - **Enhanced Decision-Making**: AI agents can analyze trends and patterns in data, provide insights, and even suggest actions, helping stakeholders make informed decisions based on factual data rather than intuition alone. + + ## 3. Popular AI Agent Frameworks + Several frameworks have emerged to facilitate the development of AI agents, each with its own unique features and capabilities. Some of the most popular frameworks include: + + - **Autogen**: A framework designed to streamline the development of AI agents through automation of code generation. + - **Semantic Kernel**: Focuses on natural language processing and understanding, enabling agents to comprehend user intentions better. + - **Promptflow**: Provides tools for developers to create conversational agents that can navigate complex interactions seamlessly. + - **Langchain**: Specializes in leveraging various APIs to ensure agents can access and utilize external data effectively. + - **CrewAI**: Aimed at collaborative environments, CrewAI strengthens teamwork by facilitating communication through AI-driven insights. + - **MemGPT**: Combines memory-optimized architectures with generative capabilities, allowing for more personalized interactions with users. + + These frameworks empower developers to build versatile and intelligent agents that can engage users, perform advanced analytics, and execute various tasks aligned with organizational goals. + + ## 4. AI Agents in Human Resources + AI agents are revolutionizing HR practices by automating and optimizing key functions: + + - **Recruiting**: AI agents can screen resumes, schedule interviews, and even conduct initial assessments, thus accelerating the hiring process while minimizing biases. + - **Succession Planning**: AI systems analyze employee performance data and potential, helping organizations identify future leaders and plan appropriate training. + - **Employee Engagement**: Chatbots powered by AI can facilitate feedback loops between employees and management, promoting an open culture and addressing concerns promptly. + + As AI continues to evolve, HR departments leveraging these agents can realize substantial improvements in both efficiency and employee satisfaction. + + ## 5. AI Agents in Finance + The finance sector is seeing extensive integration of AI agents that enhance financial practices: + + - **Expense Tracking**: Automated systems manage and monitor expenses, flagging anomalies and offering recommendations based on spending patterns. + - **Risk Assessment**: AI models assess credit risk and uncover potential fraud by analyzing transaction data and behavioral patterns. + - **Investment Decisions**: AI agents provide stock predictions and analytics based on historical data and current market conditions, empowering investors with informative insights. + + The incorporation of AI agents into finance is fostering a more responsive and risk-aware financial landscape. + + ## 6. Market Trends and Investments + The growth of AI agents has attracted significant investment, especially amidst the rising popularity of chatbots and generative AI technologies. Companies and entrepreneurs are eager to explore the potential of these systems, recognizing their ability to streamline operations and improve customer engagement. + + Conversely, corporations like Microsoft are taking strides to integrate AI agents into their product offerings, with enhancements to their Copilot 365 applications. This strategic move emphasizes the importance of AI literacy in the modern workplace and indicates the stabilizing of AI agents as essential business tools. + + ## 7. Future Predictions and Implications + Experts predict that AI agents will transform essential aspects of work life. As we look toward the future, several anticipated changes include: + + - Enhanced integration of AI agents across all business functions, creating interconnected systems that leverage data from various departmental silos for comprehensive decision-making. + - Continued advancement of AI technologies, resulting in smarter, more adaptable agents capable of learning and evolving from user interactions. + - Increased regulatory scrutiny to ensure ethical use, especially concerning data privacy and employee surveillance as AI agents become more prevalent. + + To stay competitive and harness the full potential of AI agents, organizations must remain vigilant about latest developments in AI technology and consider continuous learning and adaptation in their strategic planning. + + ## 8. Conclusion + The emergence of AI agents is undeniably reshaping the workplace landscape in 5. With their ability to automate tasks, enhance efficiency, and improve decision-making, AI agents are critical in driving operational success. Organizations must embrace and adapt to AI developments to thrive in an increasingly digital business environment. + ``` + + + + + +Parabéns! + +Você configurou seu projeto de tripulação com sucesso e está pronto para começar a construir seus próprios fluxos de trabalho baseados em agentes! + + +### Observação sobre Consistência nos Nomes + +Os nomes utilizados nos seus arquivos YAML (`agents.yaml` e `tasks.yaml`) devem corresponder aos nomes dos métodos no seu código Python. +Por exemplo, você pode referenciar o agente para tarefas específicas a partir do arquivo `tasks.yaml`. +Essa consistência de nomes permite que a CrewAI conecte automaticamente suas configurações ao seu código; caso contrário, sua tarefa não reconhecerá a referência corretamente. + +#### Exemplos de Referências + + + Observe como usamos o mesmo nome para o agente no arquivo `agents.yaml` (`email_summarizer`) e no método do arquivo `crew.py` (`email_summarizer`). + + +```yaml agents.yaml +email_summarizer: + role: > + Email Summarizer + goal: > + Summarize emails into a concise and clear summary + backstory: > + You will create a 5 bullet point summary of the report + llm: provider/model-id # Add your choice of model here +``` + + + Observe como usamos o mesmo nome para a tarefa no arquivo `tasks.yaml` (`email_summarizer_task`) e no método no arquivo `crew.py` (`email_summarizer_task`). + + +```yaml tasks.yaml +email_summarizer_task: + description: > + Summarize the email into a 5 bullet point summary + expected_output: > + A 5 bullet point summary of the email + agent: email_summarizer + context: + - reporting_task + - research_task +``` + +## Fazendo o Deploy da Sua Tripulação + +A forma mais fácil de fazer deploy da sua tripulação em produção é através da [CrewAI Enterprise](http://app.crewai.com). + +Assista a este vídeo tutorial para uma demonstração detalhada de como fazer deploy da sua tripulação na [CrewAI Enterprise](http://app.crewai.com) usando a CLI. + + + + + + Comece com o CrewAI Enterprise e faça o deploy da sua tripulação em ambiente de produção com apenas alguns cliques. + + + Participe da nossa comunidade open source para discutir ideias, compartilhar seus projetos e conectar-se com outros desenvolvedores CrewAI. + + diff --git a/docs/pt-BR/snippets/snippet-intro.mdx b/docs/pt-BR/snippets/snippet-intro.mdx new file mode 100644 index 000000000..a6c3f2170 --- /dev/null +++ b/docs/pt-BR/snippets/snippet-intro.mdx @@ -0,0 +1 @@ +Um dos princípios fundamentais do desenvolvimento de software é o DRY (Don't Repeat Yourself, ou Não Se Repita). Esse princípio também se aplica à documentação. Se você perceber que está repetindo o mesmo conteúdo em vários lugares, considere criar um snippet personalizado para manter seu conteúdo sincronizado. \ No newline at end of file diff --git a/docs/pt-BR/telemetry.mdx b/docs/pt-BR/telemetry.mdx new file mode 100644 index 000000000..7f1ab4ca4 --- /dev/null +++ b/docs/pt-BR/telemetry.mdx @@ -0,0 +1,67 @@ +--- +title: Telemetria +description: Entendendo os dados de telemetria coletados pelo CrewAI e como eles contribuem para o aprimoramento da biblioteca. +icon: signal-stream +--- + +## Telemetria + + + Por padrão, não coletamos dados que possam ser considerados informações pessoais segundo a GDPR e outras regulamentações de privacidade. + Coletamos nomes das ferramentas e funções dos agentes, portanto, evite incluir qualquer informação pessoal nos nomes das ferramentas ou nas funções dos agentes. + Como nenhuma informação pessoal é coletada, não é necessário se preocupar com localidade dos dados. + Quando `share_crew` está ativado, dados adicionais são coletados e podem conter informações pessoais caso sejam incluídas pelo usuário. + Usuários devem tomar cuidado ao habilitar este recurso para garantir conformidade com regulamentações de privacidade. + + +O CrewAI utiliza telemetria anônima para coletar estatísticas de uso com o objetivo principal de aprimorar a biblioteca. +Nosso foco está em melhorar e desenvolver as funcionalidades, integrações e ferramentas mais utilizadas pelos usuários. + +É fundamental compreender que, por padrão, **NENHUM dado pessoal é coletado** referente a prompts, descrições de tarefas, histórias ou objetivos dos agentes, +uso de ferramentas, chamadas de API, respostas, quaisquer dados processados pelos agentes ou segredos e variáveis de ambiente. +Quando o recurso `share_crew` está ativado, dados detalhados, incluindo descrições das tarefas, histórias ou objetivos dos agentes e outros atributos específicos são coletados +para fornecer insights mais detalhados. Essa coleta expandida pode incluir informações pessoais caso o usuário as tenha inserido em seus crews ou tarefas. +Usuários devem considerar cuidadosamente o conteúdo de seus crews e tarefas antes de habilitar o `share_crew`. +A telemetria pode ser desabilitada ao definir a variável de ambiente `CREWAI_DISABLE_TELEMETRY` como `true` ou ao definir `OTEL_SDK_DISABLED` como `true` (observe que esta última desabilita toda instrumentação OpenTelemetry globalmente). + +### Exemplos: +```python +# Desabilitar apenas a telemetria do CrewAI +os.environ['CREWAI_DISABLE_TELEMETRY'] = 'true' + +# Desabilitar todo o OpenTelemetry (incluindo CrewAI) +os.environ['OTEL_SDK_DISABLED'] = 'true' +``` + +### Explicação dos Dados: +| Padrão | Dados | Razão e Especificidades | +|--------|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------| +| Sim | Versão do CrewAI e Python | Rastreia versões dos softwares. Exemplo: CrewAI v1.2.3, Python 3.8.10. Sem dados pessoais. | +| Sim | Metadados do Crew | Inclui: chave e ID gerados aleatoriamente, tipo de processo (ex: 'sequential', 'parallel'), flag booleana para uso de memória (true/false), quantidade de tarefas, quantidade de agentes. Tudo não pessoal. | +| Sim | Dados do Agente | Inclui: chave e ID gerados aleatoriamente, nome da função (não deve incluir info pessoal), configurações booleanas (verbose, delegação habilitada, execução de código permitida), máximo de iterações, máximo de RPM, limite de tentativas, info do LLM (ver Atributos LLM), lista de nomes de ferramentas (não deve conter info pessoal). Sem dados pessoais. | +| Sim | Metadados da Tarefa | Inclui: chave e ID gerados aleatoriamente, configurações de execução booleanas (async_execution, human_input), função e chave do agente associado, lista de nomes de ferramentas. Tudo não pessoal. | +| Sim | Estatísticas de Uso de Ferramentas | Inclui: nome da ferramenta (não deve incluir info pessoal), número de tentativas de uso (inteiro), atributos LLM utilizados. Sem dados pessoais. | +| Sim | Dados de Execução de Testes | Inclui: chave e ID aleatórias do crew, número de iterações, nome do modelo usado, score de qualidade (float), tempo de execução (em segundos). Tudo não pessoal. | +| Sim | Dados do Ciclo de Vida da Tarefa | Inclui: horários de criação, início/fim de execução, identificadores de crew e tarefa. Armazenado como spans com timestamps. Sem dados pessoais. | +| Sim | Atributos do LLM | Inclui: nome, model_name, model, top_k, temperatura e nome da classe do LLM. Todos técnicos, sem dados pessoais. | +| Sim | Tentativa de Deploy do Crew pelo CLI do crewAI | Inclui: O fato de um deploy estar sendo realizado e o crew id, e se está tentando buscar logs, sem mais dados. | +| Não | Dados Expandidos do Agente | Inclui: descrição do objetivo, texto da história, identificador de arquivo i18n prompt. Usuários devem garantir que não haja info pessoal nesses campos de texto. | +| Não | Informações Detalhadas da Tarefa | Inclui: descrição da tarefa, descrição do resultado esperado, referências de contexto. Usuários devem garantir que não haja info pessoal nessas áreas. | +| Não | Informações de Ambiente | Inclui: plataforma, release, sistema, versão e quantidade de CPUs. Exemplo: 'Windows 10', 'x86_64'. Sem dados pessoais. | +| Não | Entradas e Saídas de Crew e Tarefas | Inclui: parâmetros de entrada e resultados como dados não identificáveis. Usuários devem garantir que não haja info pessoal. | +| Não | Dados Abrangentes de Execução do Crew | Inclui: logs detalhados das operações do crew, dados de todos os agentes e tarefas, resultado final. Tudo de natureza técnica, sem dados pessoais. | + + + "Não" na coluna "Padrão" indica que esse dado só é coletado quando `share_crew` está configurado como `true`. + + +### Compartilhamento Avançado de Telemetria (Opt-In) + +Usuários podem optar por compartilhar toda a telemetria habilitando o atributo `share_crew` como `True` nas configurações do seu crew. +Ao habilitar `share_crew`, há coleta detalhada dos dados de execução do crew e das tarefas, incluindo `goal`, `backstory`, `context` e `output` das tarefas. +Isso permite uma compreensão mais profunda dos padrões de uso. + + + Se você habilitar o `share_crew`, os dados coletados podem incluir informações pessoais caso estas estejam presentes nas configurações do crew, descrições de tarefas ou outputs. + Os usuários devem revisar cuidadosamente seus dados e garantir conformidade com a GDPR e outras regulamentações de privacidade antes de habilitar esse recurso. + \ No newline at end of file diff --git a/docs/pt-BR/tools/ai-ml/aimindtool.mdx b/docs/pt-BR/tools/ai-ml/aimindtool.mdx new file mode 100644 index 000000000..6cf9e1259 --- /dev/null +++ b/docs/pt-BR/tools/ai-ml/aimindtool.mdx @@ -0,0 +1,118 @@ +--- +title: AI Mind Tool +description: O `AIMindTool` foi desenvolvido para consultar fontes de dados em linguagem natural. +icon: brain +--- + +# `AIMindTool` + +## Descrição + +O `AIMindTool` é um wrapper em torno do [AI-Minds](https://mindsdb.com/minds) fornecido pela [MindsDB](https://mindsdb.com/). Ele permite que você consulte fontes de dados em linguagem natural, bastando configurar os parâmetros de conexão. Essa ferramenta é útil quando você precisa de respostas para perguntas utilizando dados armazenados em diversas fontes, incluindo PostgreSQL, MySQL, MariaDB, ClickHouse, Snowflake e Google BigQuery. + +Minds são sistemas de IA que funcionam de forma similar aos grandes modelos de linguagem (LLMs), mas vão além ao responder qualquer pergunta sobre qualquer dado. Isso é realizado por meio de: +- Seleção dos dados mais relevantes para a resposta utilizando busca paramétrica +- Compreensão do significado e fornecimento de respostas dentro do contexto correto através de busca semântica +- Entrega de respostas precisas ao analisar dados e utilizar modelos de machine learning (ML) + +## Instalação + +Para incorporar esta ferramenta ao seu projeto, é necessário instalar o Minds SDK: + +```shell +uv add minds-sdk +``` + +## Passos para Começar + +Para utilizar o `AIMindTool` de maneira eficaz, siga estes passos: + +1. **Instalação de Pacotes**: Verifique se os pacotes `crewai[tools]` e `minds-sdk` estão instalados no seu ambiente Python. +2. **Obtenção da Chave de API**: Cadastre-se para uma conta Minds [aqui](https://mdb.ai/register) e obtenha uma chave de API. +3. **Configuração do Ambiente**: Armazene sua chave de API obtida em uma variável de ambiente chamada `MINDS_API_KEY` para facilitar seu uso pela ferramenta. + +## Exemplo + +O exemplo a seguir demonstra como inicializar a ferramenta e executar uma consulta: + +```python Code +from crewai_tools import AIMindTool + +# Initialize the AIMindTool +aimind_tool = AIMindTool( + datasources=[ + { + "description": "house sales data", + "engine": "postgres", + "connection_data": { + "user": "demo_user", + "password": "demo_password", + "host": "samples.mindsdb.com", + "port": 5432, + "database": "demo", + "schema": "demo_data" + }, + "tables": ["house_sales"] + } + ] +) + +# Run a natural language query +result = aimind_tool.run("How many 3 bedroom houses were sold in 2008?") +print(result) +``` + +## Parâmetros + +O `AIMindTool` aceita os seguintes parâmetros: + +- **api_key**: Opcional. Sua chave de API da Minds. Se não for fornecida, será lida da variável de ambiente `MINDS_API_KEY`. +- **datasources**: Uma lista de dicionários, cada um contendo as seguintes chaves: + - **description**: Uma descrição dos dados contidos na fonte de dados. + - **engine**: O engine (ou tipo) da fonte de dados. + - **connection_data**: Um dicionário contendo os parâmetros de conexão da fonte de dados. + - **tables**: Uma lista de tabelas que a fonte de dados irá utilizar. Isso é opcional e pode ser omitido caso todas as tabelas da fonte de dados devam ser utilizadas. + +Uma lista das fontes de dados suportadas e seus parâmetros de conexão pode ser encontrada [aqui](https://docs.mdb.ai/docs/data_sources). + +## Exemplo de Integração com Agente + +Veja como integrar o `AIMindTool` com um agente CrewAI: + +```python Code +from crewai import Agent +from crewai.project import agent +from crewai_tools import AIMindTool + +# Initialize the tool +aimind_tool = AIMindTool( + datasources=[ + { + "description": "sales data", + "engine": "postgres", + "connection_data": { + "user": "your_user", + "password": "your_password", + "host": "your_host", + "port": 5432, + "database": "your_db", + "schema": "your_schema" + }, + "tables": ["sales"] + } + ] +) + +# Define an agent with the AIMindTool +@agent +def data_analyst(self) -> Agent: + return Agent( + config=self.agents_config["data_analyst"], + allow_delegation=False, + tools=[aimind_tool] + ) +``` + +## Conclusão + +O `AIMindTool` oferece uma forma poderosa de consultar suas fontes de dados utilizando linguagem natural, facilitando a extração de insights sem a necessidade de escrever consultas SQL complexas. Ao conectar diversas fontes de dados e aproveitar a tecnologia AI-Minds, essa ferramenta permite que agentes acessem e analisem dados de maneira eficiente. \ No newline at end of file diff --git a/docs/pt-BR/tools/ai-ml/codeinterpretertool.mdx b/docs/pt-BR/tools/ai-ml/codeinterpretertool.mdx new file mode 100644 index 000000000..6841379ef --- /dev/null +++ b/docs/pt-BR/tools/ai-ml/codeinterpretertool.mdx @@ -0,0 +1,209 @@ +--- +title: Interpretador de Código +description: O `CodeInterpreterTool` é uma poderosa ferramenta projetada para executar código Python 3 em um ambiente seguro e isolado. +icon: code-simple +--- + +# `CodeInterpreterTool` + +## Descrição + +O `CodeInterpreterTool` permite que agentes CrewAI executem códigos Python 3 gerados autonomamente. Essa funcionalidade é particularmente valiosa, pois permite que os agentes criem códigos, os executem, obtenham os resultados e usem essas informações para orientar decisões e ações subsequentes. + +Há diversas formas de usar esta ferramenta: + +### Container Docker (Recomendado) + +Esta é a opção principal. O código é executado em um container Docker seguro e isolado, garantindo a segurança independentemente de seu conteúdo. +Certifique-se de que o Docker esteja instalado e em funcionamento em seu sistema. Se ainda não tiver, você pode instalá-lo a partir [deste link](https://docs.docker.com/get-docker/). + +### Ambiente Sandbox + +Se o Docker não estiver disponível — seja por não estar instalado ou inacessível por qualquer motivo — o código será executado em um ambiente Python restrito, chamado de sandbox. +Esse ambiente é bastante limitado, com restrições severas a vários módulos e funções embutidas. + +### Execução Não Segura + +**NÃO RECOMENDADO PARA PRODUÇÃO** +Este modo permite a execução de qualquer código Python, inclusive chamadas perigosas para os módulos `sys, os..` e semelhantes. [Veja aqui](/pt-BR/tools/ai-ml/codeinterpretertool#enabling-unsafe-mode) como habilitar este modo. + +## Registro de Logs + +O `CodeInterpreterTool` registra a estratégia de execução selecionada no STDOUT. + + +## Instalação + +Para utilizar esta ferramenta, você precisa instalar o pacote de ferramentas CrewAI: + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo + +O exemplo a seguir demonstra como usar o `CodeInterpreterTool` com um agente CrewAI: + +```python Code +from crewai import Agent, Task, Crew, Process +from crewai_tools import CodeInterpreterTool + +# Initialize the tool +code_interpreter = CodeInterpreterTool() + +# Define an agent that uses the tool +programmer_agent = Agent( + role="Python Programmer", + goal="Write and execute Python code to solve problems", + backstory="An expert Python programmer who can write efficient code to solve complex problems.", + tools=[code_interpreter], + verbose=True, +) + +# Example task to generate and execute code +coding_task = Task( + description="Write a Python function to calculate the Fibonacci sequence up to the 10th number and print the result.", + expected_output="The Fibonacci sequence up to the 10th number.", + agent=programmer_agent, +) + +# Create and run the crew +crew = Crew( + agents=[programmer_agent], + tasks=[coding_task], + verbose=True, + process=Process.sequential, +) +result = crew.kickoff() +``` + +Você também pode habilitar a execução de código diretamente ao criar um agente: + +```python Code +from crewai import Agent + +# Create an agent with code execution enabled +programmer_agent = Agent( + role="Python Programmer", + goal="Write and execute Python code to solve problems", + backstory="An expert Python programmer who can write efficient code to solve complex problems.", + allow_code_execution=True, # This automatically adds the CodeInterpreterTool + verbose=True, +) +``` + +### Habilitando o `unsafe_mode` + +```python Code +from crewai_tools import CodeInterpreterTool + +code = """ +import os +os.system("ls -la") +""" + +CodeInterpreterTool(unsafe_mode=True).run(code=code) +``` + +## Parâmetros + +O `CodeInterpreterTool` aceita os seguintes parâmetros durante a inicialização: + +- **user_dockerfile_path**: Opcional. Caminho para um Dockerfile personalizado a ser utilizado pelo container do interpretador de código. +- **user_docker_base_url**: Opcional. URL do daemon Docker que será usado para rodar o container. +- **unsafe_mode**: Opcional. Indica se o código será executado diretamente na máquina hospedeira ao invés de um container Docker ou sandbox. O padrão é `False`. Use com cautela! +- **default_image_tag**: Opcional. Tag padrão da imagem Docker. O padrão é `code-interpreter:latest` + +Ao utilizar a ferramenta com um agente, o agente precisará fornecer: + +- **code**: Obrigatório. O código Python 3 a ser executado. +- **libraries_used**: Opcional. Uma lista de bibliotecas usadas no código que precisam ser instaladas. O padrão é `[]` + +## Exemplo de Integração com Agente + +Aqui está um exemplo mais detalhado de como integrar o `CodeInterpreterTool` com um agente CrewAI: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import CodeInterpreterTool + +# Initialize the tool +code_interpreter = CodeInterpreterTool() + +# Define an agent that uses the tool +data_analyst = Agent( + role="Data Analyst", + goal="Analyze data using Python code", + backstory="""You are an expert data analyst who specializes in using Python + to analyze and visualize data. You can write efficient code to process + large datasets and extract meaningful insights.""", + tools=[code_interpreter], + verbose=True, +) + +# Create a task for the agent +analysis_task = Task( + description=""" + Write Python code to: + 1. Generate a random dataset of 100 points with x and y coordinates + 2. Calculate the correlation coefficient between x and y + 3. Create a scatter plot of the data + 4. Print the correlation coefficient and save the plot as 'scatter.png' + + Make sure to handle any necessary imports and print the results. + """, + expected_output="The correlation coefficient and confirmation that the scatter plot has been saved.", + agent=data_analyst, +) + +# Run the task +crew = Crew( + agents=[data_analyst], + tasks=[analysis_task], + verbose=True, + process=Process.sequential, +) +result = crew.kickoff() +``` + +## Detalhes de Implementação + +O `CodeInterpreterTool` utiliza Docker para criar um ambiente seguro para execução de código: + +```python Code +class CodeInterpreterTool(BaseTool): + name: str = "Code Interpreter" + description: str = "Interprets Python3 code strings with a final print statement." + args_schema: Type[BaseModel] = CodeInterpreterSchema + default_image_tag: str = "code-interpreter:latest" + + def _run(self, **kwargs) -> str: + code = kwargs.get("code", self.code) + libraries_used = kwargs.get("libraries_used", []) + + if self.unsafe_mode: + return self.run_code_unsafe(code, libraries_used) + else: + return self.run_code_safety(code, libraries_used) +``` + +A ferramenta executa os seguintes passos: +1. Verifica se a imagem Docker existe ou a constrói, caso necessário +2. Cria um container Docker com o diretório de trabalho atual montado +3. Instala quaisquer bibliotecas necessárias especificadas pelo agente +4. Executa o código Python dentro do container +5. Retorna a saída da execução do código +6. Limpa o ambiente, parando e removendo o container + +## Considerações de Segurança + +Por padrão, o `CodeInterpreterTool` executa o código em um container Docker isolado, fornecendo uma camada de segurança. No entanto, ainda há algumas considerações importantes: + +1. O container Docker tem acesso ao diretório de trabalho atual, então arquivos sensíveis podem ser potencialmente acessados. +2. Caso o container Docker não esteja disponível e o código precise ser executado de forma segura, ele será executado em um ambiente sandbox. Por motivos de segurança, a instalação de bibliotecas arbitrárias não é permitida +3. O parâmetro `unsafe_mode` permite que códigos sejam executados diretamente na máquina hospedeira, o que deve ser usado apenas em ambientes confiáveis. +4. Tenha cautela ao permitir que agentes instalem bibliotecas arbitrárias, pois estas podem incluir códigos maliciosos. + +## Conclusão + +O `CodeInterpreterTool` oferece uma maneira poderosa para que agentes CrewAI executem código Python em um ambiente relativamente seguro. Permitindo que agentes escrevam e executem códigos, ele amplia significativamente sua capacidade de resolução de problemas, especialmente para tarefas que envolvem análise de dados, cálculos ou outros trabalhos computacionais. Esta ferramenta é especialmente útil para agentes que precisam realizar operações complexas que são mais eficientemente expressas em código do que em linguagem natural. diff --git a/docs/pt-BR/tools/ai-ml/dalletool.mdx b/docs/pt-BR/tools/ai-ml/dalletool.mdx new file mode 100644 index 000000000..bc16f45a7 --- /dev/null +++ b/docs/pt-BR/tools/ai-ml/dalletool.mdx @@ -0,0 +1,51 @@ +--- +title: Ferramenta DALL-E +description: A `DallETool` é uma ferramenta poderosa projetada para gerar imagens a partir de descrições textuais. +icon: image +--- + +# `DallETool` + +## Descrição + +Esta ferramenta é utilizada para dar ao Agente a capacidade de gerar imagens usando o modelo DALL-E. Trata-se de um modelo baseado em transformer que gera imagens a partir de descrições textuais. +Esta ferramenta permite que o Agente gere imagens com base no texto de entrada fornecido pelo usuário. + +## Instalação + +Instale o pacote crewai_tools +```shell +pip install 'crewai[tools]' +``` + +## Exemplo + +Lembre-se de que, ao usar esta ferramenta, o texto deve ser gerado pelo próprio Agente. O texto deve ser uma descrição da imagem que você deseja gerar. + +```python Code +from crewai_tools import DallETool + +Agent( + ... + tools=[DallETool()], +) +``` + +Se necessário, você também pode ajustar os parâmetros do modelo DALL-E passando-os como argumentos para a classe `DallETool`. Por exemplo: + +```python Code +from crewai_tools import DallETool + +dalle_tool = DallETool(model="dall-e-3", + size="1024x1024", + quality="standard", + n=1) + +Agent( + ... + tools=[dalle_tool] +) +``` + +Os parâmetros são baseados no método `client.images.generate` da API OpenAI. Para mais informações sobre os parâmetros, +consulte a [documentação da API OpenAI](https://platform.openai.com/docs/guides/images/introduction?lang=python). \ No newline at end of file diff --git a/docs/pt-BR/tools/ai-ml/langchaintool.mdx b/docs/pt-BR/tools/ai-ml/langchaintool.mdx new file mode 100644 index 000000000..49bb52f81 --- /dev/null +++ b/docs/pt-BR/tools/ai-ml/langchaintool.mdx @@ -0,0 +1,57 @@ +--- +title: Ferramenta LangChain +description: O `LangChainTool` é um wrapper para ferramentas LangChain e mecanismos de consulta. +icon: link +--- + +## `LangChainTool` + + + CrewAI integra-se perfeitamente com a abrangente [lista de ferramentas](https://python.langchain.com/docs/integrations/tools/) do LangChain, todas as quais podem ser usadas com CrewAI. + + +```python Code +import os +from dotenv import load_dotenv +from crewai import Agent, Task, Crew +from crewai.tools import BaseTool +from pydantic import Field +from langchain_community.utilities import GoogleSerperAPIWrapper + +# Set up your SERPER_API_KEY key in an .env file, eg: +# SERPER_API_KEY= +load_dotenv() + +search = GoogleSerperAPIWrapper() + +class SearchTool(BaseTool): + name: str = "Search" + description: str = "Useful for search-based queries. Use this to find current information about markets, companies, and trends." + search: GoogleSerperAPIWrapper = Field(default_factory=GoogleSerperAPIWrapper) + + def _run(self, query: str) -> str: + """Execute the search query and return results""" + try: + return self.search.run(query) + except Exception as e: + return f"Error performing search: {str(e)}" + +# Create Agents +researcher = Agent( + role='Research Analyst', + goal='Gather current market data and trends', + backstory="""You are an expert research analyst with years of experience in + gathering market intelligence. You're known for your ability to find + relevant and up-to-date market information and present it in a clear, + actionable format.""", + tools=[SearchTool()], + verbose=True +) + +# rest of the code ... +``` + +## Conclusão + +As ferramentas são fundamentais para ampliar as capacidades dos agentes CrewAI, permitindo que realizem uma ampla variedade de tarefas e colaborem de forma eficaz. +Ao construir soluções com CrewAI, aproveite tanto ferramentas personalizadas quanto existentes para potencializar seus agentes e aprimorar o ecossistema de IA. Considere utilizar tratamento de erros, mecanismos de cache e a flexibilidade dos argumentos das ferramentas para otimizar o desempenho e as capacidades dos seus agentes. \ No newline at end of file diff --git a/docs/pt-BR/tools/ai-ml/llamaindextool.mdx b/docs/pt-BR/tools/ai-ml/llamaindextool.mdx new file mode 100644 index 000000000..35d11a0d5 --- /dev/null +++ b/docs/pt-BR/tools/ai-ml/llamaindextool.mdx @@ -0,0 +1,146 @@ +--- +title: Ferramenta LlamaIndex +description: A `LlamaIndexTool` é um wrapper para ferramentas e mecanismos de consulta do LlamaIndex. +icon: address-book +--- + +# `LlamaIndexTool` + +## Descrição + +A `LlamaIndexTool` foi projetada para ser um wrapper geral em torno das ferramentas e mecanismos de consulta do LlamaIndex, permitindo que você aproveite os recursos do LlamaIndex em pipelines de RAG/agent como ferramentas que podem ser acopladas aos agentes do CrewAI. Essa ferramenta permite integrar de forma transparente as poderosas capacidades de processamento e recuperação de dados do LlamaIndex em seus fluxos de trabalho com o CrewAI. + +## Instalação + +Para utilizar esta ferramenta, é necessário instalar o LlamaIndex: + +```shell +uv add llama-index +``` + +## Passos para Começar + +Para utilizar a `LlamaIndexTool` de forma eficaz, siga os passos abaixo: + +1. **Instale o LlamaIndex**: Instale o pacote LlamaIndex usando o comando acima. +2. **Configure o LlamaIndex**: Siga a [documentação do LlamaIndex](https://docs.llamaindex.ai/) para configurar um pipeline de RAG/agent. +3. **Crie uma Ferramenta ou Mecanismo de Consulta**: Crie uma ferramenta ou mecanismo de consulta do LlamaIndex que você deseja usar com o CrewAI. + +## Exemplo + +Os exemplos a seguir demonstram como inicializar a ferramenta a partir de diferentes componentes do LlamaIndex: + +### A partir de uma ferramenta do LlamaIndex + +```python Code +from crewai_tools import LlamaIndexTool +from crewai import Agent +from llama_index.core.tools import FunctionTool + +# Exemplo 1: Inicializando a partir do FunctionTool +def search_data(query: str) -> str: + """Busca por informações nos dados.""" + # Sua implementação aqui + return f"Results for: {query}" + +# Criação de um LlamaIndex FunctionTool +og_tool = FunctionTool.from_defaults( + search_data, + name="DataSearchTool", + description="Search for information in the data" +) + +# Envolvendo com a LlamaIndexTool +tool = LlamaIndexTool.from_tool(og_tool) + +# Definindo um agente que utiliza a ferramenta +@agent +def researcher(self) -> Agent: + ''' + Este agente usa a LlamaIndexTool para buscar informações. + ''' + return Agent( + config=self.agents_config["researcher"], + tools=[tool] + ) +``` + +### A partir de Ferramentas do LlamaHub + +```python Code +from crewai_tools import LlamaIndexTool +from llama_index.tools.wolfram_alpha import WolframAlphaToolSpec + +# Inicializando a partir das ferramentas do LlamaHub +wolfram_spec = WolframAlphaToolSpec(app_id="your_app_id") +wolfram_tools = wolfram_spec.to_tool_list() +tools = [LlamaIndexTool.from_tool(t) for t in wolfram_tools] +``` + +### A partir de um mecanismo de consulta do LlamaIndex + +```python Code +from crewai_tools import LlamaIndexTool +from llama_index.core import VectorStoreIndex +from llama_index.core.readers import SimpleDirectoryReader + +# Carregar documentos +documents = SimpleDirectoryReader("./data").load_data() + +# Criar um índice +index = VectorStoreIndex.from_documents(documents) + +# Criar um mecanismo de consulta +query_engine = index.as_query_engine() + +# Criar uma LlamaIndexTool a partir do mecanismo de consulta +query_tool = LlamaIndexTool.from_query_engine( + query_engine, + name="Company Data Query Tool", + description="Use this tool to lookup information in company documents" +) +``` + +## Métodos da Classe + +A `LlamaIndexTool` oferece dois métodos de classe principais para criar instâncias: + +### from_tool + +Cria uma `LlamaIndexTool` a partir de uma ferramenta do LlamaIndex. + +```python Code +@classmethod +def from_tool(cls, tool: Any, **kwargs: Any) -> "LlamaIndexTool": + # Implementation details +``` + +### from_query_engine + +Cria uma `LlamaIndexTool` a partir de um mecanismo de consulta do LlamaIndex. + +```python Code +@classmethod +def from_query_engine( + cls, + query_engine: Any, + name: Optional[str] = None, + description: Optional[str] = None, + return_direct: bool = False, + **kwargs: Any, +) -> "LlamaIndexTool": + # Implementation details +``` + +## Parâmetros + +O método `from_query_engine` aceita os seguintes parâmetros: + +- **query_engine**: Obrigatório. O mecanismo de consulta do LlamaIndex a ser envolvido. +- **name**: Opcional. O nome da ferramenta. +- **description**: Opcional. A descrição da ferramenta. +- **return_direct**: Opcional. Define se deve retornar a resposta diretamente. O padrão é `False`. + +## Conclusão + +A `LlamaIndexTool` oferece uma maneira poderosa de integrar as capacidades do LlamaIndex aos agentes do CrewAI. Ao envolver ferramentas e mecanismos de consulta do LlamaIndex, ela permite que os agentes utilizem funcionalidades sofisticadas de recuperação e processamento de dados, aprimorando sua capacidade de trabalhar com fontes de informação complexas. \ No newline at end of file diff --git a/docs/pt-BR/tools/ai-ml/overview.mdx b/docs/pt-BR/tools/ai-ml/overview.mdx new file mode 100644 index 000000000..61b477402 --- /dev/null +++ b/docs/pt-BR/tools/ai-ml/overview.mdx @@ -0,0 +1,65 @@ +--- +title: "Visão Geral" +description: "Aproveite serviços de IA, gere imagens, processe visão e construa sistemas inteligentes" +icon: "face-smile" +--- + +Essas ferramentas se integram com serviços de IA e machine learning para aprimorar seus agentes com capacidades avançadas como geração de imagens, processamento de visão e execução inteligente de código. + +## **Ferramentas Disponíveis** + + + + Gere imagens com IA utilizando o modelo DALL-E da OpenAI. + + + + Processe e analise imagens com capacidades de visão computacional. + + + + Capacidades avançadas de raciocínio e tomada de decisão com IA. + + + + Construa bases de conhecimento e sistemas de recuperação com LlamaIndex. + + + + Integre com LangChain para fluxos de trabalho de IA complexos. + + + + Implemente sistemas de Geração Aumentada por Recuperação (RAG). + + + + Execute código Python e realize análises de dados. + + + + + +## **Casos de Uso Comuns** + +- **Geração de Conteúdo**: Crie imagens, textos e conteúdo multimídia +- **Análise de Dados**: Execute código e analise conjuntos de dados complexos +- **Sistemas de Conhecimento**: Construa sistemas RAG e bancos de dados inteligentes +- **Visão Computacional**: Processe e compreenda conteúdo visual +- **Segurança em IA**: Implemente moderação de conteúdo e checagens de segurança + +```python +from crewai_tools import DallETool, VisionTool, CodeInterpreterTool + +# Create AI tools +image_generator = DallETool() +vision_processor = VisionTool() +code_executor = CodeInterpreterTool() + +# Add to your agent +agent = Agent( + role="AI Specialist", + tools=[image_generator, vision_processor, code_executor], + goal="Create and analyze content using AI capabilities" +) +``` diff --git a/docs/pt-BR/tools/ai-ml/ragtool.mdx b/docs/pt-BR/tools/ai-ml/ragtool.mdx new file mode 100644 index 000000000..8f9264399 --- /dev/null +++ b/docs/pt-BR/tools/ai-ml/ragtool.mdx @@ -0,0 +1,172 @@ +--- +title: Ferramenta RAG +description: O `RagTool` é uma ferramenta dinâmica de base de conhecimento para responder perguntas usando Geração Aumentada por Recuperação. +icon: vector-square +--- + +# `RagTool` + +## Descrição + +O `RagTool` foi desenvolvido para responder perguntas aproveitando o poder da Geração Aumentada por Recuperação (RAG) através do EmbedChain. +Ele fornece uma base de conhecimento dinâmica que pode ser consultada para recuperar informações relevantes de várias fontes de dados. +Esta ferramenta é particularmente útil para aplicações que exigem acesso a uma ampla variedade de informações e precisam fornecer respostas contextualmente relevantes. + +## Exemplo + +O exemplo a seguir demonstra como inicializar a ferramenta e usá-la com diferentes fontes de dados: + +```python Code +from crewai_tools import RagTool + +# Create a RAG tool with default settings +rag_tool = RagTool() + +# Add content from a file +rag_tool.add(data_type="file", path="path/to/your/document.pdf") + +# Add content from a web page +rag_tool.add(data_type="web_page", url="https://example.com") + +# Define an agent with the RagTool +@agent +def knowledge_expert(self) -> Agent: + ''' + This agent uses the RagTool to answer questions about the knowledge base. + ''' + return Agent( + config=self.agents_config["knowledge_expert"], + allow_delegation=False, + tools=[rag_tool] + ) +``` + +## Fontes de Dados Suportadas + +O `RagTool` pode ser utilizado com uma grande variedade de fontes de dados, incluindo: + +- 📰 Arquivos PDF +- 📊 Arquivos CSV +- 📃 Arquivos JSON +- 📝 Texto +- 📁 Diretórios/Pastas +- 🌐 Páginas web em HTML +- 📽️ Canais do YouTube +- 📺 Vídeos do YouTube +- 📚 Sites de documentação +- 📝 Arquivos MDX +- 📄 Arquivos DOCX +- 🧾 Arquivos XML +- 📬 Gmail +- 📝 Repositórios GitHub +- 🐘 Bancos de dados PostgreSQL +- 🐬 Bancos de dados MySQL +- 🤖 Conversas no Slack +- 💬 Mensagens do Discord +- 🗨️ Fóruns Discourse +- 📝 Newsletters do Substack +- 🐝 Conteúdo do Beehiiv +- 💾 Arquivos Dropbox +- 🖼️ Imagens +- ⚙️ Fontes de dados personalizadas + +## Parâmetros + +O `RagTool` aceita os seguintes parâmetros: + +- **summarize**: Opcional. Indica se o conteúdo recuperado deve ser resumido. O padrão é `False`. +- **adapter**: Opcional. Um adaptador personalizado para a base de conhecimento. Se não for fornecido, será utilizado o EmbedchainAdapter. +- **config**: Opcional. Configuração para o aplicativo EmbedChain subjacente. + +## Adicionando Conteúdo + +Você pode adicionar conteúdo à base de conhecimento utilizando o método `add`: + +```python Code +# Add a PDF file +rag_tool.add(data_type="file", path="path/to/your/document.pdf") + +# Add a web page +rag_tool.add(data_type="web_page", url="https://example.com") + +# Add a YouTube video +rag_tool.add(data_type="youtube_video", url="https://www.youtube.com/watch?v=VIDEO_ID") + +# Add a directory of files +rag_tool.add(data_type="directory", path="path/to/your/directory") +``` + +## Exemplo de Integração com Agente + +Veja como integrar o `RagTool` com um agente do CrewAI: + +```python Code +from crewai import Agent +from crewai.project import agent +from crewai_tools import RagTool + +# Initialize the tool and add content +rag_tool = RagTool() +rag_tool.add(data_type="web_page", url="https://docs.crewai.com") +rag_tool.add(data_type="file", path="company_data.pdf") + +# Define an agent with the RagTool +@agent +def knowledge_expert(self) -> Agent: + return Agent( + config=self.agents_config["knowledge_expert"], + allow_delegation=False, + tools=[rag_tool] + ) +``` + +## Configuração Avançada + +É possível personalizar o comportamento do `RagTool` fornecendo um dicionário de configuração: + +```python Code +from crewai_tools import RagTool + +# Create a RAG tool with custom configuration +config = { + "app": { + "name": "custom_app", + }, + "llm": { + "provider": "openai", + "config": { + "model": "gpt-4", + } + }, + "embedding_model": { + "provider": "openai", + "config": { + "model": "text-embedding-ada-002" + } + }, + "vectordb": { + "provider": "elasticsearch", + "config": { + "collection_name": "my-collection", + "cloud_id": "deployment-name:xxxx", + "api_key": "your-key", + "verify_certs": False + } + }, + "chunker": { + "chunk_size": 400, + "chunk_overlap": 100, + "length_function": "len", + "min_chunk_size": 0 + } +} + +rag_tool = RagTool(config=config, summarize=True) +``` + +A ferramenta RAG interna utiliza o adaptador Embedchain, possibilitando que você forneça quaisquer opções de configuração suportadas pelo Embedchain. +Você pode consultar a [documentação do Embedchain](https://docs.embedchain.ai/components/introduction) para mais detalhes. +Certifique-se de revisar as opções de configuração disponíveis no arquivo .yaml. + +## Conclusão +O `RagTool` oferece uma maneira poderosa de criar e consultar bases de conhecimento a partir de diversas fontes de dados. Ao explorar a Geração Aumentada por Recuperação, ele permite que agentes acessem e recuperem informações relevantes de forma eficiente, ampliando a capacidade de fornecer respostas precisas e contextualmente apropriadas. \ No newline at end of file diff --git a/docs/pt-BR/tools/ai-ml/visiontool.mdx b/docs/pt-BR/tools/ai-ml/visiontool.mdx new file mode 100644 index 000000000..882b650c4 --- /dev/null +++ b/docs/pt-BR/tools/ai-ml/visiontool.mdx @@ -0,0 +1,49 @@ +--- +title: Vision Tool +description: O `VisionTool` foi projetado para extrair texto de imagens. +icon: eye +--- + +# `VisionTool` + +## Descrição + +Esta ferramenta é utilizada para extrair texto de imagens. Quando passada para o agente, ela extrai o texto da imagem e depois o utiliza para gerar uma resposta, relatório ou qualquer outra saída. +A URL ou o CAMINHO da imagem deve ser passado para o Agente. + +## Instalação + +Instale o pacote crewai_tools + +```shell +pip install 'crewai[tools]' +``` + +## Uso + +Para usar o VisionTool, a chave da API da OpenAI deve ser definida na variável de ambiente `OPENAI_API_KEY`. + +```python Code +from crewai_tools import VisionTool + +vision_tool = VisionTool() + +@agent +def researcher(self) -> Agent: + ''' + This agent uses the VisionTool to extract text from images. + ''' + return Agent( + config=self.agents_config["researcher"], + allow_delegation=False, + tools=[vision_tool] + ) +``` + +## Argumentos + +O VisionTool requer os seguintes argumentos: + +| Argumento | Tipo | Descrição | +| :------------------ | :------- | :------------------------------------------------------------------------------- | +| **image_path_url** | `string` | **Obrigatório**. O caminho para o arquivo de imagem do qual o texto será extraído. | \ No newline at end of file diff --git a/docs/pt-BR/tools/automation/apifyactorstool.mdx b/docs/pt-BR/tools/automation/apifyactorstool.mdx new file mode 100644 index 000000000..737b2929c --- /dev/null +++ b/docs/pt-BR/tools/automation/apifyactorstool.mdx @@ -0,0 +1,99 @@ +--- +title: Apify Actors +description: "`ApifyActorsTool` permite que você execute Apify Actors para adicionar recursos de raspagem de dados na web, coleta, extração de dados e automação web aos seus fluxos de trabalho CrewAI." +# hack to use custom Apify icon +icon: "); -webkit-mask-image: url('https://upload.wikimedia.org/wikipedia/commons/a/ae/Apify.svg');/*" +--- + +# `ApifyActorsTool` + +Integre [Apify Actors](https://apify.com/actors) nos seus fluxos de trabalho CrewAI. + +## Descrição + +O `ApifyActorsTool` conecta [Apify Actors](https://apify.com/actors), programas em nuvem para raspagem e automação web, aos seus fluxos de trabalho CrewAI. +Utilize qualquer um dos mais de 4.000 Actors disponíveis na [Apify Store](https://apify.com/store) para casos de uso como extração de dados de redes sociais, motores de busca, mapas online, sites de e-commerce, portais de viagem ou sites em geral. + +Para mais detalhes, consulte a [integração Apify CrewAI](https://docs.apify.com/platform/integrations/crewai) na documentação do Apify. + +## Passos para começar + + + + Instale `crewai[tools]` e `langchain-apify` usando pip: `pip install 'crewai[tools]' langchain-apify`. + + + Cadastre-se no [Apify Console](https://console.apify.com/) e obtenha seu [token de API do Apify](https://console.apify.com/settings/integrations). + + + Defina seu token de API do Apify na variável de ambiente `APIFY_API_TOKEN` para habilitar a funcionalidade da ferramenta. + + + +## Exemplo de uso + +Use o `ApifyActorsTool` manualmente para executar o [RAG Web Browser Actor](https://apify.com/apify/rag-web-browser) e realizar uma busca na web: + +```python +from crewai_tools import ApifyActorsTool + +# Inicialize a ferramenta com um Apify Actor +tool = ApifyActorsTool(actor_name="apify/rag-web-browser") + +# Execute a ferramenta com parâmetros de entrada +results = tool.run(run_input={"query": "What is CrewAI?", "maxResults": 5}) + +# Processe os resultados +for result in results: + print(f"URL: {result['metadata']['url']}") + print(f"Content: {result.get('markdown', 'N/A')[:100]}...") +``` + +### Saída esperada + +Veja abaixo a saída do código acima: + +```text +URL: https://www.example.com/crewai-intro +Content: CrewAI is a framework for building AI-powered workflows... +URL: https://docs.crewai.com/ +Content: Official documentation for CrewAI... +``` + +O `ApifyActorsTool` busca automaticamente a definição do Actor e o esquema de entrada no Apify utilizando o `actor_name` fornecido e então constrói a descrição da ferramenta e o esquema dos argumentos. Isso significa que você só precisa informar um `actor_name` válido, e a ferramenta faz o resto quando usada com agentes—não é necessário especificar o `run_input`. Veja como funciona: + +```python +from crewai import Agent +from crewai_tools import ApifyActorsTool + +rag_browser = ApifyActorsTool(actor_name="apify/rag-web-browser") + +agent = Agent( + role="Research Analyst", + goal="Find and summarize information about specific topics", + backstory="You are an experienced researcher with attention to detail", + tools=[rag_browser], +) +``` + +Você pode executar outros Actors da [Apify Store](https://apify.com/store) apenas alterando o `actor_name` e, ao usar manualmente, ajustando o `run_input` de acordo com o esquema de entrada do Actor. + +Para um exemplo de uso com agentes, consulte o [template CrewAI Actor](https://apify.com/templates/python-crewai). + +## Configuração + +O `ApifyActorsTool` exige os seguintes inputs para funcionar: + +- **`actor_name`** + O ID do Apify Actor a ser executado, por exemplo, `"apify/rag-web-browser"`. Explore todos os Actors na [Apify Store](https://apify.com/store). +- **`run_input`** + Um dicionário de parâmetros de entrada para o Actor ao executar a ferramenta manualmente. + - Por exemplo, para o Actor `apify/rag-web-browser`: `{"query": "search term", "maxResults": 5}` + - Veja o [schema de entrada do Actor](https://apify.com/apify/rag-web-browser/input-schema) para a lista de parâmetros de entrada. + +## Recursos + +- **[Apify](https://apify.com/)**: Explore a plataforma Apify. +- **[Como criar um agente de IA no Apify](https://blog.apify.com/how-to-build-an-ai-agent/)** - Um guia completo, passo a passo, para criar, publicar e monetizar agentes de IA na plataforma Apify. +- **[RAG Web Browser Actor](https://apify.com/apify/rag-web-browser)**: Um Actor popular para busca na web para LLMs. +- **[Guia de Integração CrewAI](https://docs.apify.com/platform/integrations/crewai)**: Siga o guia oficial para integrar Apify e CrewAI. \ No newline at end of file diff --git a/docs/pt-BR/tools/automation/composiotool.mdx b/docs/pt-BR/tools/automation/composiotool.mdx new file mode 100644 index 000000000..2abcc3b2c --- /dev/null +++ b/docs/pt-BR/tools/automation/composiotool.mdx @@ -0,0 +1,118 @@ +--- +title: Ferramenta Composio +description: O Composio oferece mais de 250 ferramentas prontas para produção para agentes de IA com gerenciamento de autenticação flexível. +icon: gear-code +--- + +# `ComposioToolSet` + +## Descrição +Composio é uma plataforma de integração que permite conectar seus agentes de IA a mais de 250 ferramentas. Os principais recursos incluem: + +- **Autenticação de Nível Empresarial**: Suporte integrado para OAuth, Chaves de API, JWT com atualização automática de token +- **Observabilidade Completa**: Logs detalhados de uso das ferramentas, registros de execução, e muito mais + +## Instalação + +Para incorporar as ferramentas Composio em seu projeto, siga as instruções abaixo: + +```shell +pip install composio-crewai +pip install crewai +``` + +Após a conclusão da instalação, execute `composio login` ou exporte sua chave de API do composio como `COMPOSIO_API_KEY`. Obtenha sua chave de API Composio [aqui](https://app.composio.dev) + +## Exemplo + +O exemplo a seguir demonstra como inicializar a ferramenta e executar uma ação do github: + +1. Inicialize o conjunto de ferramentas Composio + +```python Code +from composio_crewai import ComposioToolSet, App, Action +from crewai import Agent, Task, Crew + +toolset = ComposioToolSet() +``` + +2. Conecte sua conta do GitHub + +```shell CLI +composio add github +``` +```python Code +request = toolset.initiate_connection(app=App.GITHUB) +print(f"Open this URL to authenticate: {request.redirectUrl}") +``` + + +3. Obtenha ferramentas + +- Recuperando todas as ferramentas de um app (não recomendado em produção): +```python Code +tools = toolset.get_tools(apps=[App.GITHUB]) +``` + +- Filtrando ferramentas com base em tags: +```python Code +tag = "users" + +filtered_action_enums = toolset.find_actions_by_tags( + App.GITHUB, + tags=[tag], +) + +tools = toolset.get_tools(actions=filtered_action_enums) +``` + +- Filtrando ferramentas com base no caso de uso: +```python Code +use_case = "Star a repository on GitHub" + +filtered_action_enums = toolset.find_actions_by_use_case( + App.GITHUB, use_case=use_case, advanced=False +) + +tools = toolset.get_tools(actions=filtered_action_enums) +``` +Defina `advanced` como True para obter ações para casos de uso complexos + +- Usando ferramentas específicas: + +Neste exemplo, usaremos a ação `GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER` do app GitHub. +```python Code +tools = toolset.get_tools( + actions=[Action.GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER] +) +``` +Saiba mais sobre como filtrar ações [aqui](https://docs.composio.dev/patterns/tools/use-tools/use-specific-actions) + +4. Defina o agente + +```python Code +crewai_agent = Agent( + role="GitHub Agent", + goal="You take action on GitHub using GitHub APIs", + backstory="You are AI agent that is responsible for taking actions on GitHub on behalf of users using GitHub APIs", + verbose=True, + tools=tools, + llm= # pass an llm +) +``` + +5. Execute a tarefa + +```python Code +task = Task( + description="Star a repo composiohq/composio on GitHub", + agent=crewai_agent, + expected_output="Status of the operation", +) + +crew = Crew(agents=[crewai_agent], tasks=[task]) + +crew.kickoff() +``` + +* Uma lista mais detalhada de ferramentas pode ser encontrada [aqui](https://app.composio.dev) \ No newline at end of file diff --git a/docs/pt-BR/tools/automation/multiontool.mdx b/docs/pt-BR/tools/automation/multiontool.mdx new file mode 100644 index 000000000..43b46501a --- /dev/null +++ b/docs/pt-BR/tools/automation/multiontool.mdx @@ -0,0 +1,126 @@ +--- +title: MultiOn Tool +description: O `MultiOnTool` permite que agentes CrewAI naveguem e interajam com a web por meio de instruções em linguagem natural. +icon: globe +--- + +## Visão Geral + +O `MultiOnTool` foi projetado para envolver as capacidades de navegação web do [MultiOn](https://docs.multion.ai/welcome), permitindo que agentes CrewAI controlem navegadores web usando instruções em linguagem natural. Esta ferramenta facilita a navegação fluida, tornando-se um recurso essencial para projetos que requerem interação dinâmica com dados web e automação de tarefas baseadas na web. + +## Instalação + +Para utilizar esta ferramenta, é necessário instalar o pacote MultiOn: + +```shell +uv add multion +``` + +Você também precisará instalar a extensão de navegador do MultiOn e habilitar o uso da API. + +## Passos para Começar + +Para usar o `MultiOnTool` de forma eficaz, siga estes passos: + +1. **Instale o CrewAI**: Certifique-se de que o pacote `crewai[tools]` esteja instalado em seu ambiente Python. +2. **Instale e utilize o MultiOn**: Siga a [documentação do MultiOn](https://docs.multion.ai/learn/browser-extension) para instalar a extensão de navegador do MultiOn. +3. **Habilite o Uso da API**: Clique na extensão do MultiOn na pasta de extensões do seu navegador (não no ícone flutuante do MultiOn na página web) para abrir as configurações da extensão. Clique na opção para habilitar a API (API Enabled). + +## Exemplo + +O exemplo a seguir demonstra como inicializar a ferramenta e executar uma tarefa de navegação web: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import MultiOnTool + +# Initialize the tool +multion_tool = MultiOnTool(api_key="YOUR_MULTION_API_KEY", local=False) + +# Define an agent that uses the tool +browser_agent = Agent( + role="Browser Agent", + goal="Control web browsers using natural language", + backstory="An expert browsing agent.", + tools=[multion_tool], + verbose=True, +) + +# Example task to search and summarize news +browse_task = Task( + description="Summarize the top 3 trending AI News headlines", + expected_output="A summary of the top 3 trending AI News headlines", + agent=browser_agent, +) + +# Create and run the crew +crew = Crew(agents=[browser_agent], tasks=[browse_task]) +result = crew.kickoff() +``` + +## Parâmetros + +O `MultiOnTool` aceita os seguintes parâmetros durante a inicialização: + +- **api_key**: Opcional. Especifica a chave da API do MultiOn. Se não for fornecida, a ferramenta procurará pela variável de ambiente `MULTION_API_KEY`. +- **local**: Opcional. Defina como `True` para executar o agente localmente em seu navegador. Certifique-se de que a extensão do MultiOn está instalada e a opção API Enabled está marcada. O padrão é `False`. +- **max_steps**: Opcional. Define o número máximo de etapas que o agente MultiOn pode executar para um comando. O padrão é `3`. + +## Uso + +Ao utilizar o `MultiOnTool`, o agente fornecerá instruções em linguagem natural que a ferramenta traduzirá em ações de navegação web. A ferramenta retorna os resultados da sessão de navegação juntamente com um status. + +```python Code +# Example of using the tool with an agent +browser_agent = Agent( + role="Web Browser Agent", + goal="Search for and summarize information from the web", + backstory="An expert at finding and extracting information from websites.", + tools=[multion_tool], + verbose=True, +) + +# Create a task for the agent +search_task = Task( + description="Search for the latest AI news on TechCrunch and summarize the top 3 headlines", + expected_output="A summary of the top 3 AI news headlines from TechCrunch", + agent=browser_agent, +) + +# Run the task +crew = Crew(agents=[browser_agent], tasks=[search_task]) +result = crew.kickoff() +``` + +Se o status retornado for `CONTINUE`, o agente deve ser instruído a reenviar a mesma instrução para continuar a execução. + +## Detalhes de Implementação + +O `MultiOnTool` é implementado como uma subclasse de `BaseTool` do CrewAI. Ele envolve o cliente MultiOn para fornecer capacidades de navegação web: + +```python Code +class MultiOnTool(BaseTool): + """Tool to wrap MultiOn Browse Capabilities.""" + + name: str = "Multion Browse Tool" + description: str = """Multion gives the ability for LLMs to control web browsers using natural language instructions. + If the status is 'CONTINUE', reissue the same instruction to continue execution + """ + + # Implementation details... + + def _run(self, cmd: str, *args: Any, **kwargs: Any) -> str: + """ + Run the Multion client with the given command. + + Args: + cmd (str): The detailed and specific natural language instruction for web browsing + *args (Any): Additional arguments to pass to the Multion client + **kwargs (Any): Additional keyword arguments to pass to the Multion client + """ + # Implementation details... +``` + +## Conclusão + +O `MultiOnTool` oferece uma maneira poderosa de integrar capacidades de navegação web em agentes CrewAI. Ao permitir que agentes interajam com sites por meio de instruções em linguagem natural, amplia significativamente as possibilidades para tarefas baseadas na web, desde coleta de dados e pesquisa até interações automatizadas com serviços online. \ No newline at end of file diff --git a/docs/pt-BR/tools/automation/overview.mdx b/docs/pt-BR/tools/automation/overview.mdx new file mode 100644 index 000000000..68d3b28c0 --- /dev/null +++ b/docs/pt-BR/tools/automation/overview.mdx @@ -0,0 +1,55 @@ +--- +title: "Visão Geral" +description: "Automatize fluxos de trabalho e integre com plataformas e serviços externos" +icon: "face-smile" +--- + +Essas ferramentas permitem que seus agentes automatizem fluxos de trabalho, integrem com plataformas externas e conectem-se a diversos serviços de terceiros para funcionalidades aprimoradas. + +## **Ferramentas Disponíveis** + + + + Execute atores do Apify para tarefas de automação e raspagem de dados web. + + + + Integre com centenas de aplicativos e serviços através do Composio. + + + + Automatize interações no navegador e fluxos de trabalho baseados na web. + + + +## **Casos de Uso Comuns** + +- **Automação de Fluxos de Trabalho**: Automatize tarefas e processos repetitivos +- **Integração com APIs**: Conecte-se a APIs e serviços externos +- **Sincronização de Dados**: Sincronize dados entre diferentes plataformas +- **Orquestração de Processos**: Coordene fluxos de trabalho complexos e com múltiplas etapas +- **Serviços de Terceiros**: Aproveite ferramentas e plataformas externas + +```python +from crewai_tools import ApifyActorTool, ComposioTool, MultiOnTool + +# Create automation tools +apify_automation = ApifyActorTool() +platform_integration = ComposioTool() +browser_automation = MultiOnTool() + +# Add to your agent +agent = Agent( + role="Automation Specialist", + tools=[apify_automation, platform_integration, browser_automation], + goal="Automate workflows and integrate systems" +) +``` + +## **Benefícios da Integração** + +- **Eficiência**: Reduza o trabalho manual por meio da automação +- **Escalabilidade**: Gerencie cargas de trabalho crescentes automaticamente +- **Confiabilidade**: Execução consistente de fluxos de trabalho +- **Conectividade**: Integre diferentes sistemas e plataformas +- **Produtividade**: Foque em tarefas de alto valor enquanto a automação cuida das rotinas diff --git a/docs/pt-BR/tools/cloud-storage/bedrockinvokeagenttool.mdx b/docs/pt-BR/tools/cloud-storage/bedrockinvokeagenttool.mdx new file mode 100644 index 000000000..981499dd3 --- /dev/null +++ b/docs/pt-BR/tools/cloud-storage/bedrockinvokeagenttool.mdx @@ -0,0 +1,187 @@ +--- +title: Ferramenta Bedrock Invoke Agent +description: Permite que agentes CrewAI invoquem Amazon Bedrock Agents e aproveitem suas capacidades em seus fluxos de trabalho +icon: aws +--- + +# `BedrockInvokeAgentTool` + +A `BedrockInvokeAgentTool` permite que agentes CrewAI invoquem Amazon Bedrock Agents e aproveitem suas capacidades em seus fluxos de trabalho. + +## Instalação + +```bash +uv pip install 'crewai[tools]' +``` + +## Requisitos + +- Credenciais AWS configuradas (através de variáveis de ambiente ou AWS CLI) +- Pacotes `boto3` e `python-dotenv` +- Acesso aos Amazon Bedrock Agents + +## Uso + +Veja como usar a ferramenta com um agente CrewAI: + +```python {2, 4-8} +from crewai import Agent, Task, Crew +from crewai_tools.aws.bedrock.agents.invoke_agent_tool import BedrockInvokeAgentTool + +# Initialize the tool +agent_tool = BedrockInvokeAgentTool( + agent_id="your-agent-id", + agent_alias_id="your-agent-alias-id" +) + +# Create a CrewAI agent that uses the tool +aws_expert = Agent( + role='AWS Service Expert', + goal='Help users understand AWS services and quotas', + backstory='I am an expert in AWS services and can provide detailed information about them.', + tools=[agent_tool], + verbose=True +) + +# Create a task for the agent +quota_task = Task( + description="Find out the current service quotas for EC2 in us-west-2 and explain any recent changes.", + agent=aws_expert +) + +# Create a crew with the agent +crew = Crew( + agents=[aws_expert], + tasks=[quota_task], + verbose=2 +) + +# Run the crew +result = crew.kickoff() +print(result) +``` + +## Argumentos da Ferramenta + +| Argumento | Tipo | Obrigatório | Padrão | Descrição | +|:----------|:-----|:------------|:---------|:----------------------------------------------------| +| **agent_id** | `str` | Sim | None | O identificador único do agente Bedrock | +| **agent_alias_id** | `str` | Sim | None | O identificador único do alias do agente | +| **session_id** | `str` | Não | timestamp | O identificador único da sessão | +| **enable_trace** | `bool` | Não | False | Define se o trace deve ser habilitado para debug | +| **end_session** | `bool` | Não | False | Define se a sessão deve ser encerrada após invocação | +| **description** | `str` | Não | None | Descrição personalizada para a ferramenta | + +## Variáveis de Ambiente + +```bash +BEDROCK_AGENT_ID=your-agent-id # Alternativa para passar agent_id +BEDROCK_AGENT_ALIAS_ID=your-agent-alias-id # Alternativa para passar agent_alias_id +AWS_REGION=your-aws-region # Padrão é us-west-2 +AWS_ACCESS_KEY_ID=your-access-key # Necessário para autenticação AWS +AWS_SECRET_ACCESS_KEY=your-secret-key # Necessário para autenticação AWS +``` + +## Uso Avançado + +### Fluxo de Trabalho Multiagente com Gerenciamento de Sessão + +```python {2, 4-22} +from crewai import Agent, Task, Crew, Process +from crewai_tools.aws.bedrock.agents.invoke_agent_tool import BedrockInvokeAgentTool + +# Initialize tools with session management +initial_tool = BedrockInvokeAgentTool( + agent_id="your-agent-id", + agent_alias_id="your-agent-alias-id", + session_id="custom-session-id" +) + +followup_tool = BedrockInvokeAgentTool( + agent_id="your-agent-id", + agent_alias_id="your-agent-alias-id", + session_id="custom-session-id" +) + +final_tool = BedrockInvokeAgentTool( + agent_id="your-agent-id", + agent_alias_id="your-agent-alias-id", + session_id="custom-session-id", + end_session=True +) + +# Create agents for different stages +researcher = Agent( + role='AWS Service Researcher', + goal='Gather information about AWS services', + backstory='I am specialized in finding detailed AWS service information.', + tools=[initial_tool] +) + +analyst = Agent( + role='Service Compatibility Analyst', + goal='Analyze service compatibility and requirements', + backstory='I analyze AWS services for compatibility and integration possibilities.', + tools=[followup_tool] +) + +summarizer = Agent( + role='Technical Documentation Writer', + goal='Create clear technical summaries', + backstory='I specialize in creating clear, concise technical documentation.', + tools=[final_tool] +) + +# Create tasks +research_task = Task( + description="Find all available AWS services in us-west-2 region.", + agent=researcher +) + +analysis_task = Task( + description="Analyze which services support IPv6 and their implementation requirements.", + agent=analyst +) + +summary_task = Task( + description="Create a summary of IPv6-compatible services and their key features.", + agent=summarizer +) + +# Create a crew with the agents and tasks +crew = Crew( + agents=[researcher, analyst, summarizer], + tasks=[research_task, analysis_task, summary_task], + process=Process.sequential, + verbose=2 +) + +# Run the crew +result = crew.kickoff() +``` + +## Casos de Uso + +### Colaborações Híbridas Multiagente +- Crie fluxos de trabalho onde agentes CrewAI colaboram com agentes Bedrock gerenciados executando como serviços na AWS +- Permita cenários em que o processamento de dados sensíveis ocorre dentro do seu ambiente AWS enquanto outros agentes operam externamente +- Conecte agentes CrewAI on-premises a agentes Bedrock baseados na nuvem para fluxos de trabalho distribuídos de inteligência + +### Soberania e Conformidade de Dados +- Mantenha fluxos de trabalho agentivos sensíveis a dados dentro do seu ambiente AWS enquanto permite que agentes CrewAI externos orquestrem tarefas +- Mantenha conformidade com requisitos de residência de dados processando informações sensíveis somente em sua conta AWS +- Permita colaborações multiagentes seguras onde alguns agentes não podem acessar dados privados da sua organização + +### Integração Transparente com Serviços AWS +- Acesse qualquer serviço AWS por meio do Amazon Bedrock Actions sem escrever código de integração complexo +- Permita que agentes CrewAI interajam com serviços AWS usando solicitações em linguagem natural +- Aproveite as capacidades pré-construídas dos agentes Bedrock para interagir com serviços AWS como Bedrock Knowledge Bases, Lambda e outros + +### Arquiteturas de Agentes Híbridos Escaláveis +- Realize tarefas computacionalmente intensivas em agentes Bedrock gerenciados enquanto tarefas leves rodam em CrewAI +- Escale o processamento de agentes distribuindo cargas de trabalho entre agentes CrewAI locais e agentes Bedrock na nuvem + +### Colaboração de Agentes Entre Organizações +- Permita colaboração segura entre agentes CrewAI da sua organização e agentes Bedrock de organizações parceiras +- Crie fluxos de trabalho onde a expertise externa de agentes Bedrock pode ser incorporada sem expor dados sensíveis +- Construa ecossistemas de agentes que abrangem fronteiras organizacionais mantendo segurança e controle de dados \ No newline at end of file diff --git a/docs/pt-BR/tools/cloud-storage/bedrockkbretriever.mdx b/docs/pt-BR/tools/cloud-storage/bedrockkbretriever.mdx new file mode 100644 index 000000000..b8de9e900 --- /dev/null +++ b/docs/pt-BR/tools/cloud-storage/bedrockkbretriever.mdx @@ -0,0 +1,165 @@ +--- +title: 'Bedrock Knowledge Base Retriever' +description: 'Recupere informações das Bases de Conhecimento do Amazon Bedrock usando consultas em linguagem natural' +icon: aws +--- + +# `BedrockKBRetrieverTool` + +A `BedrockKBRetrieverTool` permite que agentes CrewAI recuperem informações das Bases de Conhecimento do Amazon Bedrock usando consultas em linguagem natural. + +## Instalação + +```bash +uv pip install 'crewai[tools]' +``` + +## Requisitos + +- Credenciais AWS configuradas (via variáveis de ambiente ou AWS CLI) +- Pacotes `boto3` e `python-dotenv` +- Acesso à Base de Conhecimento do Amazon Bedrock + +## Uso + +Veja como utilizar a ferramenta com um agente CrewAI: + +```python {2, 4-17} +from crewai import Agent, Task, Crew +from crewai_tools.aws.bedrock.knowledge_base.retriever_tool import BedrockKBRetrieverTool + +# Initialize the tool +kb_tool = BedrockKBRetrieverTool( + knowledge_base_id="your-kb-id", + number_of_results=5 +) + +# Create a CrewAI agent that uses the tool +researcher = Agent( + role='Knowledge Base Researcher', + goal='Find information about company policies', + backstory='I am a researcher specialized in retrieving and analyzing company documentation.', + tools=[kb_tool], + verbose=True +) + +# Create a task for the agent +research_task = Task( + description="Find our company's remote work policy and summarize the key points.", + agent=researcher +) + +# Create a crew with the agent +crew = Crew( + agents=[researcher], + tasks=[research_task], + verbose=2 +) + +# Run the crew +result = crew.kickoff() +print(result) +``` + +## Argumentos da Ferramenta + +| Argumento | Tipo | Obrigatório | Padrão | Descrição | +|:----------|:-----|:------------|:-------|:----------| +| **knowledge_base_id** | `str` | Sim | Nenhum | O identificador único da base de conhecimento (0-10 caracteres alfanuméricos) | +| **number_of_results** | `int` | Não | 5 | Número máximo de resultados a serem retornados | +| **retrieval_configuration** | `dict` | Não | Nenhum | Configurações personalizadas para a consulta da base de conhecimento | +| **guardrail_configuration** | `dict` | Não | Nenhum | Configurações de filtragem de conteúdo | +| **next_token** | `str` | Não | Nenhum | Token para paginação | + +## Variáveis de Ambiente + +```bash +BEDROCK_KB_ID=your-knowledge-base-id # Alternativa ao uso de knowledge_base_id +AWS_REGION=your-aws-region # Padrão: us-east-1 +AWS_ACCESS_KEY_ID=your-access-key # Obrigatório para autenticação AWS +AWS_SECRET_ACCESS_KEY=your-secret-key # Obrigatório para autenticação AWS +``` + +## Formato da Resposta + +A ferramenta retorna resultados em formato JSON: + +```json +{ + "results": [ + { + "content": "Retrieved text content", + "content_type": "text", + "source_type": "S3", + "source_uri": "s3://bucket/document.pdf", + "score": 0.95, + "metadata": { + "additional": "metadata" + } + } + ], + "nextToken": "pagination-token", + "guardrailAction": "NONE" +} +``` + +## Uso Avançado + +### Configuração de Recuperação Personalizada + +```python +kb_tool = BedrockKBRetrieverTool( + knowledge_base_id="your-kb-id", + retrieval_configuration={ + "vectorSearchConfiguration": { + "numberOfResults": 10, + "overrideSearchType": "HYBRID" + } + } +) + +policy_expert = Agent( + role='Policy Expert', + goal='Analyze company policies in detail', + backstory='I am an expert in corporate policy analysis with deep knowledge of regulatory requirements.', + tools=[kb_tool] +) +``` + +## Fontes de Dados Suportadas + +- Amazon S3 +- Confluence +- Salesforce +- SharePoint +- Páginas web +- Locais de documentos personalizados +- Amazon Kendra +- Bancos de dados SQL + +## Casos de Uso + +### Integração de Conhecimento Corporativo +- Permita que agentes CrewAI acessem o conhecimento proprietário da sua organização sem expor dados sensíveis +- Permita que agentes tomem decisões baseadas nas políticas, procedimentos e documentações específicas da sua empresa +- Crie agentes capazes de responder perguntas com base na sua documentação interna mantendo a segurança dos dados + +### Conhecimento Especializado de Domínio +- Conecte agentes CrewAI a bases de conhecimento específicas do domínio (jurídico, médico, técnico) sem re-treinamento de modelos +- Aproveite repositórios de conhecimento existentes que já são mantidos no seu ambiente AWS +- Combine o raciocínio do CrewAI com informações de domínio provenientes das suas bases de conhecimento + +### Tomada de Decisão Orientada por Dados +- Baseie as respostas dos agentes CrewAI nos dados reais da sua empresa, e não apenas em conhecimento geral +- Assegure que os agentes forneçam recomendações baseadas no contexto e documentação do seu negócio +- Reduza alucinações ao recuperar informações factuais das suas bases de conhecimento + +### Acesso Escalável à Informação +- Acesse terabytes de conhecimento organizacional sem precisar incorporar tudo aos seus modelos +- Consulte dinamicamente apenas as informações relevantes conforme a necessidade de cada tarefa +- Aproveite a infraestrutura escalável da AWS para lidar com grandes bases de conhecimento de forma eficiente + +### Conformidade e Governança +- Garanta que agentes CrewAI forneçam respostas alinhadas com a documentação aprovada da sua empresa +- Crie trilhas de auditoria das fontes de informação usadas pelos agentes +- Mantenha controle sobre quais fontes de informação os seus agentes podem acessar \ No newline at end of file diff --git a/docs/pt-BR/tools/cloud-storage/overview.mdx b/docs/pt-BR/tools/cloud-storage/overview.mdx new file mode 100644 index 000000000..f98a863ad --- /dev/null +++ b/docs/pt-BR/tools/cloud-storage/overview.mdx @@ -0,0 +1,51 @@ +--- +title: "Visão Geral" +description: "Interaja com serviços em nuvem, sistemas de armazenamento e plataformas de IA baseadas em nuvem" +icon: "face-smile" +--- + +Essas ferramentas permitem que seus agentes interajam com serviços em nuvem, acessem o armazenamento em nuvem e aproveitem plataformas de IA baseadas em nuvem para operações em escala. + +## **Ferramentas Disponíveis** + + + + Leia arquivos e dados de buckets Amazon S3. + + + + Escreva e faça upload de arquivos para o armazenamento Amazon S3. + + + + Acione agentes Amazon Bedrock para tarefas orientadas por IA. + + + + Recupere informações das bases de conhecimento Amazon Bedrock. + + + +## **Casos de Uso Comuns** + +- **Armazenamento de Arquivos**: Armazene e recupere arquivos de sistemas de armazenamento em nuvem +- **Backup de Dados**: Faça backup de dados importantes no armazenamento em nuvem +- **Serviços de IA**: Acesse modelos e serviços de IA baseados em nuvem +- **Recuperação de Conhecimento**: Consulte bases de conhecimento hospedadas na nuvem +- **Operações Escaláveis**: Aproveite a infraestrutura de nuvem para processamento + +```python +from crewai_tools import S3ReaderTool, S3WriterTool, BedrockInvokeAgentTool + +# Create cloud tools +s3_reader = S3ReaderTool() +s3_writer = S3WriterTool() +bedrock_agent = BedrockInvokeAgentTool() + +# Add to your agent +agent = Agent( + role="Cloud Operations Specialist", + tools=[s3_reader, s3_writer, bedrock_agent], + goal="Manage cloud resources and AI services" +) +``` diff --git a/docs/pt-BR/tools/cloud-storage/s3readertool.mdx b/docs/pt-BR/tools/cloud-storage/s3readertool.mdx new file mode 100644 index 000000000..e2d09d6e2 --- /dev/null +++ b/docs/pt-BR/tools/cloud-storage/s3readertool.mdx @@ -0,0 +1,144 @@ +--- +title: S3 Reader Tool +description: O `S3ReaderTool` permite que agentes CrewAI leiam arquivos de buckets Amazon S3. +icon: aws +--- + +# `S3ReaderTool` + +## Descrição + +O `S3ReaderTool` foi projetado para ler arquivos de buckets Amazon S3. Esta ferramenta permite que os agentes CrewAI acessem e recuperem conteúdos armazenados no S3, tornando-a ideal para fluxos de trabalho que exigem leitura de dados, arquivos de configuração ou qualquer outro conteúdo armazenado no AWS S3. + +## Instalação + +Para utilizar esta ferramenta, é necessário instalar as dependências requeridas: + +```shell +uv add boto3 +``` + +## Passos para Começar + +Para usar o `S3ReaderTool` efetivamente, siga estes passos: + +1. **Instale as Dependências**: Instale os pacotes necessários usando o comando acima. +2. **Configure as Credenciais AWS**: Defina suas credenciais AWS como variáveis de ambiente. +3. **Inicialize a Ferramenta**: Crie uma instância da ferramenta. +4. **Especifique o Caminho S3**: Forneça o caminho S3 do arquivo que deseja ler. + +## Exemplo + +O exemplo a seguir demonstra como utilizar o `S3ReaderTool` para ler um arquivo de um bucket S3: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools.aws.s3 import S3ReaderTool + +# Initialize the tool +s3_reader_tool = S3ReaderTool() + +# Define an agent that uses the tool +file_reader_agent = Agent( + role="File Reader", + goal="Read files from S3 buckets", + backstory="An expert in retrieving and processing files from cloud storage.", + tools=[s3_reader_tool], + verbose=True, +) + +# Example task to read a configuration file +read_task = Task( + description="Read the configuration file from {my_bucket} and summarize its contents.", + expected_output="A summary of the configuration file contents.", + agent=file_reader_agent, +) + +# Create and run the crew +crew = Crew(agents=[file_reader_agent], tasks=[read_task]) +result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/config/app-config.json"}) +``` + +## Parâmetros + +O `S3ReaderTool` aceita o seguinte parâmetro quando utilizado por um agente: + +- **file_path**: Obrigatório. O caminho do arquivo S3 no formato `s3://nome-do-bucket/nome-do-arquivo`. + +## Credenciais AWS + +A ferramenta requer credenciais AWS para acessar buckets S3. Você pode configurar essas credenciais usando variáveis de ambiente: + +- **CREW_AWS_REGION**: Região AWS onde seu bucket S3 está localizado. O padrão é `us-east-1`. +- **CREW_AWS_ACCESS_KEY_ID**: Sua AWS access key ID. +- **CREW_AWS_SEC_ACCESS_KEY**: Sua AWS secret access key. + +## Uso + +Ao utilizar o `S3ReaderTool` com um agente, o agente deverá fornecer o caminho do arquivo S3: + +```python Code +# Example of using the tool with an agent +file_reader_agent = Agent( + role="File Reader", + goal="Read files from S3 buckets", + backstory="An expert in retrieving and processing files from cloud storage.", + tools=[s3_reader_tool], + verbose=True, +) + +# Create a task for the agent to read a specific file +read_config_task = Task( + description="Read the application configuration file from {my_bucket} and extract the database connection settings.", + expected_output="The database connection settings from the configuration file.", + agent=file_reader_agent, +) + +# Run the task +crew = Crew(agents=[file_reader_agent], tasks=[read_config_task]) +result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/config/app-config.json"}) +``` + +## Tratamento de Erros + +O `S3ReaderTool` inclui tratamento para erros comuns do S3: + +- Formato inválido de caminho S3 +- Arquivos ausentes ou inacessíveis +- Problemas de permissão +- Problemas com credenciais AWS + +Quando um erro ocorre, a ferramenta retorna uma mensagem de erro com detalhes sobre o problema. + +## Detalhes da Implementação + +O `S3ReaderTool` utiliza o AWS SDK for Python (boto3) para interagir com o S3: + +```python Code +class S3ReaderTool(BaseTool): + name: str = "S3 Reader Tool" + description: str = "Reads a file from Amazon S3 given an S3 file path" + + def _run(self, file_path: str) -> str: + try: + bucket_name, object_key = self._parse_s3_path(file_path) + + s3 = boto3.client( + 's3', + region_name=os.getenv('CREW_AWS_REGION', 'us-east-1'), + aws_access_key_id=os.getenv('CREW_AWS_ACCESS_KEY_ID'), + aws_secret_access_key=os.getenv('CREW_AWS_SEC_ACCESS_KEY') + ) + + # Read file content from S3 + response = s3.get_object(Bucket=bucket_name, Key=object_key) + file_content = response['Body'].read().decode('utf-8') + + return file_content + except ClientError as e: + return f"Error reading file from S3: {str(e)}" +``` + +## Conclusão + +O `S3ReaderTool` oferece uma maneira simples de ler arquivos de buckets Amazon S3. Ao permitir que agentes acessem conteúdos armazenados no S3, facilita fluxos de trabalho que necessitam de acesso a arquivos na nuvem. Esta ferramenta é especialmente útil para processamento de dados, gestão de configurações e qualquer tarefa que envolva a obtenção de informações do armazenamento AWS S3. \ No newline at end of file diff --git a/docs/pt-BR/tools/cloud-storage/s3writertool.mdx b/docs/pt-BR/tools/cloud-storage/s3writertool.mdx new file mode 100644 index 000000000..0a4d3bc9b --- /dev/null +++ b/docs/pt-BR/tools/cloud-storage/s3writertool.mdx @@ -0,0 +1,150 @@ +--- +title: Ferramenta S3 Writer +description: A `S3WriterTool` permite que agentes CrewAI escrevam conteúdo em arquivos em buckets Amazon S3. +icon: aws +--- + +# `S3WriterTool` + +## Descrição + +A `S3WriterTool` foi projetada para escrever conteúdo em arquivos em buckets Amazon S3. Esta ferramenta permite que agentes CrewAI criem ou atualizem arquivos no S3, tornando-a ideal para fluxos de trabalho que exigem armazenamento de dados, salvamento de arquivos de configuração ou persistência de qualquer outro conteúdo no armazenamento AWS S3. + +## Instalação + +Para usar esta ferramenta, você precisa instalar as dependências necessárias: + +```shell +uv add boto3 +``` + +## Passos para Começar + +Para usar a `S3WriterTool` de forma eficaz, siga estes passos: + +1. **Instale as Dependências**: Instale os pacotes necessários usando o comando acima. +2. **Configure as Credenciais AWS**: Defina suas credenciais AWS como variáveis de ambiente. +3. **Inicialize a Ferramenta**: Crie uma instância da ferramenta. +4. **Especifique o Caminho no S3 e o Conteúdo**: Forneça o caminho no S3 onde deseja gravar o arquivo e o conteúdo a ser escrito. + +## Exemplo + +O exemplo a seguir demonstra como usar a `S3WriterTool` para gravar conteúdo em um arquivo em um bucket S3: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools.aws.s3 import S3WriterTool + +# Initialize the tool +s3_writer_tool = S3WriterTool() + +# Define an agent that uses the tool +file_writer_agent = Agent( + role="File Writer", + goal="Write content to files in S3 buckets", + backstory="An expert in storing and managing files in cloud storage.", + tools=[s3_writer_tool], + verbose=True, +) + +# Example task to write a report +write_task = Task( + description="Generate a summary report of the quarterly sales data and save it to {my_bucket}.", + expected_output="Confirmation that the report was successfully saved to S3.", + agent=file_writer_agent, +) + +# Create and run the crew +crew = Crew(agents=[file_writer_agent], tasks=[write_task]) +result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/reports/quarterly-summary.txt"}) +``` + +## Parâmetros + +A `S3WriterTool` aceita os seguintes parâmetros quando utilizada por um agente: + +- **file_path**: Obrigatório. O caminho do arquivo S3 no formato `s3://bucket-name/file-name`. +- **content**: Obrigatório. O conteúdo a ser escrito no arquivo. + +## Credenciais AWS + +A ferramenta requer credenciais AWS para acessar os buckets S3. Você pode configurar essas credenciais usando variáveis de ambiente: + +- **CREW_AWS_REGION**: A região AWS onde seu bucket S3 está localizado. O padrão é `us-east-1`. +- **CREW_AWS_ACCESS_KEY_ID**: Sua AWS access key ID. +- **CREW_AWS_SEC_ACCESS_KEY**: Sua AWS secret access key. + +## Uso + +Ao usar a `S3WriterTool` com um agente, o agente precisará fornecer tanto o caminho do arquivo no S3 quanto o conteúdo a ser gravado: + +```python Code +# Example of using the tool with an agent +file_writer_agent = Agent( + role="File Writer", + goal="Write content to files in S3 buckets", + backstory="An expert in storing and managing files in cloud storage.", + tools=[s3_writer_tool], + verbose=True, +) + +# Create a task for the agent to write a specific file +write_config_task = Task( + description=""" + Create a configuration file with the following database settings: + - host: db.example.com + - port: 5432 + - username: app_user + - password: secure_password + + Save this configuration as JSON to {my_bucket}. + """, + expected_output="Confirmation that the configuration file was successfully saved to S3.", + agent=file_writer_agent, +) + +# Run the task +crew = Crew(agents=[file_writer_agent], tasks=[write_config_task]) +result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/config/db-config.json"}) +``` + +## Tratamento de Erros + +A `S3WriterTool` inclui tratamento de erros para problemas comuns no S3: + +- Formato de caminho S3 inválido +- Problemas de permissão (ex: sem acesso de gravação ao bucket) +- Problemas com credenciais AWS +- Bucket inexistente + +Quando ocorre um erro, a ferramenta retorna uma mensagem de erro que inclui detalhes sobre o problema. + +## Detalhes de Implementação + +A `S3WriterTool` utiliza o AWS SDK para Python (boto3) para interagir com o S3: + +```python Code +class S3WriterTool(BaseTool): + name: str = "S3 Writer Tool" + description: str = "Writes content to a file in Amazon S3 given an S3 file path" + + def _run(self, file_path: str, content: str) -> str: + try: + bucket_name, object_key = self._parse_s3_path(file_path) + + s3 = boto3.client( + 's3', + region_name=os.getenv('CREW_AWS_REGION', 'us-east-1'), + aws_access_key_id=os.getenv('CREW_AWS_ACCESS_KEY_ID'), + aws_secret_access_key=os.getenv('CREW_AWS_SEC_ACCESS_KEY') + ) + + s3.put_object(Bucket=bucket_name, Key=object_key, Body=content.encode('utf-8')) + return f"Successfully wrote content to {file_path}" + except ClientError as e: + return f"Error writing file to S3: {str(e)}" +``` + +## Conclusão + +A `S3WriterTool` oferece uma maneira direta de gravar conteúdo em arquivos em buckets Amazon S3. Ao permitir que agentes criem e atualizem arquivos no S3, ela facilita fluxos de trabalho que exigem armazenamento de arquivos em nuvem. Esta ferramenta é particularmente útil para persistência de dados, gerenciamento de configurações, geração de relatórios e qualquer tarefa que envolva armazenar informações no AWS S3. \ No newline at end of file diff --git a/docs/pt-BR/tools/database-data/mysqltool.mdx b/docs/pt-BR/tools/database-data/mysqltool.mdx new file mode 100644 index 000000000..42bcd7449 --- /dev/null +++ b/docs/pt-BR/tools/database-data/mysqltool.mdx @@ -0,0 +1,69 @@ +--- +title: Busca RAG no MySQL +description: O `MySQLSearchTool` foi projetado para buscar em bancos de dados MySQL e retornar os resultados mais relevantes. +icon: database +--- + +## Visão Geral + +Esta ferramenta foi desenvolvida para facilitar buscas semânticas em tabelas de bancos de dados MySQL. Utilizando a tecnologia RAG (Retrieve and Generate), +o MySQLSearchTool oferece aos usuários um meio eficiente de consultar o conteúdo de tabelas do banco de dados, especificamente adaptado para bancos MySQL. +Ela simplifica o processo de encontrar dados relevantes por meio de consultas de busca semântica, tornando-se um recurso valioso para quem precisa +realizar consultas avançadas em grandes conjuntos de dados dentro de um banco de dados MySQL. + +## Instalação + +Para instalar o pacote `crewai_tools` e utilizar o MySQLSearchTool, execute o seguinte comando no seu terminal: + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo + +Abaixo está um exemplo demonstrando como usar o MySQLSearchTool para realizar uma busca semântica em uma tabela de um banco de dados MySQL: + +```python Code +from crewai_tools import MySQLSearchTool + +# Inicialize a ferramenta com o URI do banco de dados e o nome da tabela de destino +tool = MySQLSearchTool( + db_uri='mysql://user:password@localhost:3306/mydatabase', + table_name='employees' +) +``` + +## Argumentos + +O MySQLSearchTool requer os seguintes argumentos para sua operação: + +- `db_uri`: Uma string representando o URI do banco de dados MySQL a ser consultado. Este argumento é obrigatório e deve incluir os detalhes de autenticação necessários e o local do banco de dados. +- `table_name`: Uma string especificando o nome da tabela dentro do banco de dados na qual será realizada a busca semântica. Este argumento é obrigatório. + +## Modelo e embeddings personalizados + +Por padrão, a ferramenta utiliza o OpenAI tanto para embeddings quanto para sumarização. Para customizar o modelo, você pode usar um dicionário de configuração conforme o exemplo: + +```python Code +tool = MySQLSearchTool( + config=dict( + llm=dict( + provider="ollama", # ou google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/database-data/nl2sqltool.mdx b/docs/pt-BR/tools/database-data/nl2sqltool.mdx new file mode 100644 index 000000000..df61d98c0 --- /dev/null +++ b/docs/pt-BR/tools/database-data/nl2sqltool.mdx @@ -0,0 +1,76 @@ +--- +title: NL2SQL Tool +description: O `NL2SQLTool` foi projetado para converter linguagem natural em consultas SQL. +icon: language +--- + +## Visão Geral + +Esta ferramenta é utilizada para converter linguagem natural em consultas SQL. Quando passada para o agente, ela irá gerar as consultas e, em seguida, utilizá-las para interagir com o banco de dados. + +Isso possibilita múltiplos fluxos de trabalho, como por exemplo ter um Agente acessando o banco de dados para buscar informações com base em um objetivo e, então, usar essas informações para gerar uma resposta, relatório ou qualquer outro tipo de saída. Além disso, permite que o Agente atualize o banco de dados de acordo com seu objetivo. + +**Atenção**: Certifique-se de que o Agente tenha acesso a um Read-Replica ou que seja permitido que o Agente execute consultas de inserção/atualização no banco de dados. + +## Requisitos + +- SqlAlchemy +- Qualquer biblioteca compatível com o banco de dados (ex.: psycopg2, mysql-connector-python) + +## Instalação + +Instale o pacote crewai_tools + +```shell +pip install 'crewai[tools]' +``` + +## Uso + +Para utilizar o NL2SQLTool, você precisa passar a URI do banco de dados para a ferramenta. O formato da URI deve ser `dialect+driver://username:password@host:port/database`. + +```python Code +from crewai_tools import NL2SQLTool + +# psycopg2 foi instalado para rodar este exemplo com PostgreSQL +nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db") + +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config["researcher"], + allow_delegation=False, + tools=[nl2sql] + ) +``` + +## Exemplo + +O objetivo principal da tarefa era: + +"Recupere a receita mensal média, máxima e mínima para cada cidade, mas inclua apenas cidades que tenham mais de um usuário. Além disso, conte o número de usuários em cada cidade e classifique os resultados pela receita mensal média em ordem decrescente" + +Assim, o Agente tentou obter informações do banco de dados; a primeira vez está errada, então o Agente tenta novamente, consegue a informação correta e repassa para o próximo agente. + +![alt text](https://github.com/crewAIInc/crewAI-tools/blob/main/crewai_tools/tools/nl2sql/images/image-2.png?raw=true) +![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-3.png) + +O segundo objetivo da tarefa foi: + +"Revise os dados e crie um relatório detalhado e, em seguida, crie a tabela no banco de dados com os campos baseados nos dados fornecidos. Inclua informações sobre a receita mensal média, máxima e mínima para cada cidade, mas apenas inclua cidades que possuam mais de um usuário. Também conte o número de usuários em cada cidade e classifique os resultados pela receita mensal média em ordem decrescente." + +Agora as coisas começam a ficar interessantes: o Agente gera a consulta SQL não só para criar a tabela, mas também inserir os dados na tabela. E, ao final, o Agente ainda retorna o relatório final que condiz exatamente com o que estava no banco de dados. + +![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-4.png) +![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-5.png) + +![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-9.png) +![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-7.png) + +Este é um exemplo simples de como o NL2SQLTool pode ser utilizado para interagir com o banco de dados e gerar relatórios baseados nos dados do banco. + +A ferramenta oferece possibilidades infinitas para a lógica do Agente e como ele pode interagir com o banco de dados. + +```md + DB -> Agent -> ... -> Agent -> DB +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/database-data/overview.mdx b/docs/pt-BR/tools/database-data/overview.mdx new file mode 100644 index 000000000..3782bddfa --- /dev/null +++ b/docs/pt-BR/tools/database-data/overview.mdx @@ -0,0 +1,58 @@ +--- +title: "Visão Geral" +description: "Conecte-se a bancos de dados, armazenamentos vetoriais e data warehouses para acesso abrangente aos dados" +icon: "face-smile" +--- + +Essas ferramentas permitem que seus agentes interajam com diversos sistemas de banco de dados, desde bancos de dados SQL tradicionais até armazenamentos vetoriais modernos e data warehouses. + +## **Ferramentas Disponíveis** + + + + Conecte-se e faça consultas a bancos de dados MySQL com operações SQL. + + + + Pesquise e consulte bancos de dados PostgreSQL de forma eficiente. + + + + Acesse o data warehouse Snowflake para análises e relatórios. + + + + Converta automaticamente consultas em linguagem natural para comandos SQL. + + + + Pesquise embeddings vetoriais usando o banco de dados vetorial Qdrant. + + + + Realize buscas semânticas com o banco de dados vetorial Weaviate. + + + +## **Casos de Uso Comuns** + +- **Análise de Dados**: Consulte bancos de dados para inteligência de negócios e relatórios +- **Busca Vetorial**: Encontre conteúdos similares utilizando embeddings semânticos +- **Operações ETL**: Extraia, transforme e carregue dados entre sistemas +- **Análise em Tempo Real**: Acesse dados ao vivo para tomada de decisões + +```python +from crewai_tools import MySQLTool, QdrantVectorSearchTool, NL2SQLTool + +# Create database tools +mysql_db = MySQLTool() +vector_search = QdrantVectorSearchTool() +nl_to_sql = NL2SQLTool() + +# Add to your agent +agent = Agent( + role="Data Analyst", + tools=[mysql_db, vector_search, nl_to_sql], + goal="Extract insights from various data sources" +) +``` diff --git a/docs/pt-BR/tools/database-data/pgsearchtool.mdx b/docs/pt-BR/tools/database-data/pgsearchtool.mdx new file mode 100644 index 000000000..5a6708f84 --- /dev/null +++ b/docs/pt-BR/tools/database-data/pgsearchtool.mdx @@ -0,0 +1,82 @@ +--- +title: PG RAG Search +description: O `PGSearchTool` foi desenvolvido para pesquisar bancos de dados PostgreSQL e retornar os resultados mais relevantes. +icon: elephant +--- + +## Visão geral + + + O PGSearchTool está atualmente em desenvolvimento. Este documento descreve a funcionalidade e a interface pretendidas. + Conforme o desenvolvimento avança, esteja ciente de que alguns recursos podem não estar disponíveis ou podem mudar. + + +## Descrição + +O PGSearchTool é concebido como uma ferramenta poderosa para facilitar buscas semânticas em tabelas de bancos de dados PostgreSQL. Aproveitando tecnologia avançada de Recuperação e Geração (RAG), +ele visa fornecer um meio eficiente para consultar o conteúdo de tabelas de banco de dados, especificamente voltado para bancos de dados PostgreSQL. +O objetivo da ferramenta é simplificar o processo de encontrar dados relevantes por meio de consultas semânticas, oferecendo um recurso valioso para usuários que precisam realizar buscas avançadas em +grandes volumes de dados dentro de um ambiente PostgreSQL. + +## Instalação + +O pacote `crewai_tools`, que incluirá o PGSearchTool assim que for lançado, pode ser instalado usando o comando abaixo: + +```shell +pip install 'crewai[tools]' +``` + + + O PGSearchTool ainda não está disponível na versão atual do pacote `crewai_tools`. Este comando de instalação será atualizado assim que a ferramenta for lançada. + + +## Exemplo de Uso + +Abaixo está um exemplo proposto mostrando como utilizar o PGSearchTool para realizar uma busca semântica em uma tabela dentro de um banco de dados PostgreSQL: + +```python Code +from crewai_tools import PGSearchTool + +# Inicialize a ferramenta com a URI do banco de dados e o nome da tabela alvo +tool = PGSearchTool( + db_uri='postgresql://user:password@localhost:5432/mydatabase', + table_name='employees' +) +``` + +## Argumentos + +O PGSearchTool foi projetado para exigir os seguintes argumentos para seu funcionamento: + +| Argumento | Tipo | Descrição | +|:---------------|:---------|:---------------------------------------------------------------------------------------------------------------------------------| +| **db_uri** | `string` | **Obrigatório**. Uma string que representa a URI do banco de dados PostgreSQL a ser consultado. Este argumento será obrigatório e deve incluir os detalhes necessários de autenticação e a localização do banco de dados. | +| **table_name** | `string` | **Obrigatório**. Uma string que especifica o nome da tabela dentro do banco de dados na qual a busca semântica será realizada. Este argumento também será obrigatório. | + +## Modelo Personalizado e Embeddings + +A ferramenta pretende usar OpenAI tanto para embeddings quanto para sumarização por padrão. Os usuários terão a opção de personalizar o modelo usando um dicionário de configuração, conforme mostrado abaixo: + +```python Code +tool = PGSearchTool( + config=dict( + llm=dict( + provider="ollama", # ou google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", # ou openai, ollama, ... + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/database-data/qdrantvectorsearchtool.mdx b/docs/pt-BR/tools/database-data/qdrantvectorsearchtool.mdx new file mode 100644 index 000000000..ddaa9d8cf --- /dev/null +++ b/docs/pt-BR/tools/database-data/qdrantvectorsearchtool.mdx @@ -0,0 +1,272 @@ +--- +title: 'Qdrant Vector Search Tool' +description: 'Capacidades de busca semântica para agentes CrewAI usando o banco de dados vetorial Qdrant' +icon: vector-square +--- + +## Visão Geral + +A ferramenta Qdrant Vector Search permite adicionar capacidades de busca semântica aos seus agentes CrewAI utilizando o [Qdrant](https://qdrant.tech/), um mecanismo de busca por similaridade vetorial. Com essa ferramenta, seus agentes podem pesquisar em documentos armazenados em uma coleção Qdrant usando similaridade semântica. + +## Instalação + +Instale os pacotes necessários: + +```bash +uv add qdrant-client +``` + +## Uso Básico + +Veja um exemplo mínimo de como utilizar a ferramenta: + +```python +from crewai import Agent +from crewai_tools import QdrantVectorSearchTool + +# Inicialize a ferramenta +qdrant_tool = QdrantVectorSearchTool( + qdrant_url="your_qdrant_url", + qdrant_api_key="your_qdrant_api_key", + collection_name="your_collection" +) + +# Crie um agente que utiliza a ferramenta +agent = Agent( + role="Research Assistant", + goal="Find relevant information in documents", + tools=[qdrant_tool] +) + +# A ferramenta usará automaticamente embeddings da OpenAI +# e retornará os 3 resultados mais relevantes com pontuação > 0.35 +``` + +## Exemplo Completo e Funcional + +Veja um exemplo completo mostrando como: +1. Extrair texto de um PDF +2. Gerar embeddings usando OpenAI +3. Armazenar no Qdrant +4. Criar um fluxo de trabalho RAG agente CrewAI para busca semântica + +```python +import os +import uuid +import pdfplumber +from openai import OpenAI +from dotenv import load_dotenv +from crewai import Agent, Task, Crew, Process, LLM +from crewai_tools import QdrantVectorSearchTool +from qdrant_client import QdrantClient +from qdrant_client.models import PointStruct, Distance, VectorParams + +# Carregar variáveis de ambiente +load_dotenv() + +# Inicializar cliente OpenAI +client = OpenAI(api_key=os.getenv("OPENAI_API_KEY")) + +# Extrair texto do PDF +def extract_text_from_pdf(pdf_path): + text = [] + with pdfplumber.open(pdf_path) as pdf: + for page in pdf.pages: + page_text = page.extract_text() + if page_text: + text.append(page_text.strip()) + return text + +# Gerar embeddings da OpenAI +def get_openai_embedding(text): + response = client.embeddings.create( + input=text, + model="text-embedding-3-small" + ) + return response.data[0].embedding + +# Armazenar texto e embeddings no Qdrant +def load_pdf_to_qdrant(pdf_path, qdrant, collection_name): + # Extrair texto do PDF + text_chunks = extract_text_from_pdf(pdf_path) + + # Criar coleção no Qdrant + if qdrant.collection_exists(collection_name): + qdrant.delete_collection(collection_name) + qdrant.create_collection( + collection_name=collection_name, + vectors_config=VectorParams(size=1536, distance=Distance.COSINE) + ) + + # Armazenar embeddings + points = [] + for chunk in text_chunks: + embedding = get_openai_embedding(chunk) + points.append(PointStruct( + id=str(uuid.uuid4()), + vector=embedding, + payload={"text": chunk} + )) + qdrant.upsert(collection_name=collection_name, points=points) + +# Inicializar cliente Qdrant e carregar dados +qdrant = QdrantClient( + url=os.getenv("QDRANT_URL"), + api_key=os.getenv("QDRANT_API_KEY") +) +collection_name = "example_collection" +pdf_path = "path/to/your/document.pdf" +load_pdf_to_qdrant(pdf_path, qdrant, collection_name) + +# Inicializar ferramenta de busca Qdrant +qdrant_tool = QdrantVectorSearchTool( + qdrant_url=os.getenv("QDRANT_URL"), + qdrant_api_key=os.getenv("QDRANT_API_KEY"), + collection_name=collection_name, + limit=3, + score_threshold=0.35 +) + +# Criar agentes CrewAI +search_agent = Agent( + role="Senior Semantic Search Agent", + goal="Find and analyze documents based on semantic search", + backstory="""You are an expert research assistant who can find relevant + information using semantic search in a Qdrant database.""", + tools=[qdrant_tool], + verbose=True +) + +answer_agent = Agent( + role="Senior Answer Assistant", + goal="Generate answers to questions based on the context provided", + backstory="""You are an expert answer assistant who can generate + answers to questions based on the context provided.""", + tools=[qdrant_tool], + verbose=True +) + +# Definir tarefas +search_task = Task( + description="""Search for relevant documents about the {query}. + Your final answer should include: + - The relevant information found + - The similarity scores of the results + - The metadata of the relevant documents""", + agent=search_agent +) + +answer_task = Task( + description="""Given the context and metadata of relevant documents, + generate a final answer based on the context.""", + agent=answer_agent +) + +# Executar fluxo CrewAI +crew = Crew( + agents=[search_agent, answer_agent], + tasks=[search_task, answer_task], + process=Process.sequential, + verbose=True +) + +result = crew.kickoff( + inputs={"query": "What is the role of X in the document?"} +) +print(result) +``` + +## Parâmetros da Ferramenta + +### Parâmetros Obrigatórios +- `qdrant_url` (str): URL do seu servidor Qdrant +- `qdrant_api_key` (str): Chave de API para autenticação com o Qdrant +- `collection_name` (str): Nome da coleção Qdrant a ser pesquisada + +### Parâmetros Opcionais +- `limit` (int): Número máximo de resultados a serem retornados (padrão: 3) +- `score_threshold` (float): Limite mínimo de similaridade (padrão: 0.35) +- `custom_embedding_fn` (Callable[[str], list[float]]): Função personalizada para vetorização de textos + +## Parâmetros de Busca + +A ferramenta aceita estes parâmetros em seu schema: +- `query` (str): Consulta de busca para encontrar documentos similares +- `filter_by` (str, opcional): Campo de metadado para filtrar +- `filter_value` (str, opcional): Valor para filtrar + +## Formato de Retorno + +A ferramenta retorna resultados no formato JSON: + +```json +[ + { + "metadata": { + // Todos os metadados armazenados junto com o documento + }, + "context": "O conteúdo textual real do documento", + "distance": 0.95 // Pontuação de similaridade + } +] +``` + +## Embedding Padrão + +Por padrão, a ferramenta utiliza o modelo `text-embedding-3-small` da OpenAI para vetorização. Isso requer: +- Chave de API da OpenAI definida na variável de ambiente: `OPENAI_API_KEY` + +## Embeddings Personalizados + +Em vez de utilizar o modelo padrão de embeddings, você pode utilizar sua própria função de embeddings nos casos em que: + +1. Deseja usar um modelo de embeddings diferente (ex: Cohere, HuggingFace, modelos Ollama) +2. Precisa reduzir custos utilizando modelos de código aberto +3. Tem requisitos específicos quanto à dimensão dos vetores ou à qualidade dos embeddings +4. Deseja utilizar embeddings específicos para determinado domínio (ex: textos médicos ou jurídicos) + +Veja um exemplo utilizando um modelo HuggingFace: + +```python +from transformers import AutoTokenizer, AutoModel +import torch + +# Carregar modelo e tokenizer +tokenizer = AutoTokenizer.from_pretrained('sentence-transformers/all-MiniLM-L6-v2') +model = AutoModel.from_pretrained('sentence-transformers/all-MiniLM-L6-v2') + +def custom_embeddings(text: str) -> list[float]: + # Tokenizar e obter saídas do modelo + inputs = tokenizer(text, return_tensors="pt", padding=True, truncation=True) + outputs = model(**inputs) + + # Usar mean pooling para obter o embedding do texto + embeddings = outputs.last_hidden_state.mean(dim=1) + + # Converter para lista de floats e retornar + return embeddings[0].tolist() + +# Usar embeddings personalizados com a ferramenta +tool = QdrantVectorSearchTool( + qdrant_url="your_url", + qdrant_api_key="your_key", + collection_name="your_collection", + custom_embedding_fn=custom_embeddings # Passe sua função personalizada +) +``` + +## Tratamento de Erros + +A ferramenta trata os seguintes erros específicos: +- Lança ImportError se `qdrant-client` não estiver instalado (com opção de instalar automaticamente) +- Lança ValueError se `QDRANT_URL` não estiver definido +- Solicita instalação de `qdrant-client` se estiver ausente utilizando `uv add qdrant-client` + +## Variáveis de Ambiente + +Variáveis de ambiente obrigatórias: +```bash +export QDRANT_URL="your_qdrant_url" # Se não for informado no construtor +export QDRANT_API_KEY="your_api_key" # Se não for informado no construtor +export OPENAI_API_KEY="your_openai_key" # Se estiver usando embeddings padrão +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/database-data/snowflakesearchtool.mdx b/docs/pt-BR/tools/database-data/snowflakesearchtool.mdx new file mode 100644 index 000000000..e3fc66396 --- /dev/null +++ b/docs/pt-BR/tools/database-data/snowflakesearchtool.mdx @@ -0,0 +1,202 @@ +--- +title: Snowflake Search Tool +description: O `SnowflakeSearchTool` permite que agentes CrewAI executem consultas SQL e realizem buscas semânticas em data warehouses Snowflake. +icon: snowflake +--- + +# `SnowflakeSearchTool` + +## Descrição + +O `SnowflakeSearchTool` foi desenvolvido para conectar-se a data warehouses Snowflake e executar consultas SQL com recursos avançados como pool de conexões, lógica de tentativas e execução assíncrona. Esta ferramenta permite que agentes CrewAI interajam com bases de dados Snowflake, sendo ideal para tarefas de análise de dados, relatórios e inteligência de negócios que requerem acesso a dados empresariais armazenados no Snowflake. + +## Instalação + +Para utilizar esta ferramenta, é necessário instalar as dependências requeridas: + +```shell +uv add cryptography snowflake-connector-python snowflake-sqlalchemy +``` + +Ou, alternativamente: + +```shell +uv sync --extra snowflake +``` + +## Passos para Começar + +Para usar eficazmente o `SnowflakeSearchTool`, siga estes passos: + +1. **Instale as Dependências**: Instale os pacotes necessários usando um dos comandos acima. +2. **Configure a Conexão com o Snowflake**: Crie um objeto `SnowflakeConfig` com suas credenciais do Snowflake. +3. **Inicialize a Ferramenta**: Crie uma instância da ferramenta com a configuração necessária. +4. **Execute Consultas**: Utilize a ferramenta para rodar consultas SQL no seu banco de dados Snowflake. + +## Exemplo + +O exemplo a seguir demonstra como usar o `SnowflakeSearchTool` para consultar dados de um banco de dados Snowflake: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import SnowflakeSearchTool, SnowflakeConfig + +# Create Snowflake configuration +config = SnowflakeConfig( + account="your_account", + user="your_username", + password="your_password", + warehouse="COMPUTE_WH", + database="your_database", + snowflake_schema="your_schema" +) + +# Initialize the tool +snowflake_tool = SnowflakeSearchTool(config=config) + +# Define an agent that uses the tool +data_analyst_agent = Agent( + role="Data Analyst", + goal="Analyze data from Snowflake database", + backstory="An expert data analyst who can extract insights from enterprise data.", + tools=[snowflake_tool], + verbose=True, +) + +# Example task to query sales data +query_task = Task( + description="Query the sales data for the last quarter and summarize the top 5 products by revenue.", + expected_output="A summary of the top 5 products by revenue for the last quarter.", + agent=data_analyst_agent, +) + +# Create and run the crew +crew = Crew(agents=[data_analyst_agent], + tasks=[query_task]) +result = crew.kickoff() +``` + +Você também pode customizar a ferramenta com parâmetros adicionais: + +```python Code +# Initialize the tool with custom parameters +snowflake_tool = SnowflakeSearchTool( + config=config, + pool_size=10, + max_retries=5, + retry_delay=2.0, + enable_caching=True +) +``` + +## Parâmetros + +### Parâmetros do SnowflakeConfig + +A classe `SnowflakeConfig` aceita os seguintes parâmetros: + +- **account**: Obrigatório. Identificador da conta Snowflake. +- **user**: Obrigatório. Nome de usuário do Snowflake. +- **password**: Opcional*. Senha do Snowflake. +- **private_key_path**: Opcional*. Caminho para o arquivo de chave privada (alternativa à senha). +- **warehouse**: Obrigatório. Nome do warehouse do Snowflake. +- **database**: Obrigatório. Banco de dados padrão. +- **snowflake_schema**: Obrigatório. Schema padrão. +- **role**: Opcional. Papel de usuário Snowflake. +- **session_parameters**: Opcional. Parâmetros de sessão personalizados como dicionário. + +*É necessário fornecer `password` ou `private_key_path`. + +### Parâmetros do SnowflakeSearchTool + +O `SnowflakeSearchTool` aceita os seguintes parâmetros durante a inicialização: + +- **config**: Obrigatório. Um objeto `SnowflakeConfig` contendo detalhes da conexão. +- **pool_size**: Opcional. Número de conexões no pool. O padrão é 5. +- **max_retries**: Opcional. Número máximo de tentativas para consultas que falharem. Padrão é 3. +- **retry_delay**: Opcional. Intervalo entre tentativas em segundos. Padrão é 1.0. +- **enable_caching**: Opcional. Define se o cache de resultados de consultas será habilitado. Padrão é True. + +## Uso + +Ao utilizar o `SnowflakeSearchTool`, você deve fornecer os seguintes parâmetros: + +- **query**: Obrigatório. Consulta SQL a ser executada. +- **database**: Opcional. Sobrescreve o banco de dados padrão especificado na configuração. +- **snowflake_schema**: Opcional. Sobrescreve o schema padrão especificado na configuração. +- **timeout**: Opcional. Tempo limite da consulta em segundos. O padrão é 300. + +A ferramenta retornará os resultados da consulta como uma lista de dicionários, onde cada dicionário representa uma linha com os nomes das colunas como chaves. + +```python Code +# Example of using the tool with an agent +data_analyst = Agent( + role="Data Analyst", + goal="Analyze sales data from Snowflake", + backstory="An expert data analyst with experience in SQL and data visualization.", + tools=[snowflake_tool], + verbose=True +) + +# The agent will use the tool with parameters like: +# query="SELECT product_name, SUM(revenue) as total_revenue FROM sales GROUP BY product_name ORDER BY total_revenue DESC LIMIT 5" +# timeout=600 + +# Create a task for the agent +analysis_task = Task( + description="Query the sales database and identify the top 5 products by revenue for the last quarter.", + expected_output="A detailed analysis of the top 5 products by revenue.", + agent=data_analyst +) + +# Run the task +crew = Crew( + agents=[data_analyst], + tasks=[analysis_task] +) +result = crew.kickoff() +``` + +## Recursos Avançados + +### Pool de Conexões + +O `SnowflakeSearchTool` implementa pool de conexões para melhorar a performance reutilizando conexões com o banco de dados. Você pode controlar o tamanho do pool com o parâmetro `pool_size`. + +### Tentativas Automáticas + +A ferramenta tenta novamente consultas que falharem automaticamente, usando backoff exponencial. O comportamento das tentativas pode ser ajustado pelos parâmetros `max_retries` e `retry_delay`. + +### Cache de Resultados de Consultas + +Para melhorar a performance em consultas repetidas, a ferramenta pode armazenar resultados em cache. Este recurso está habilitado por padrão, mas pode ser desativado ao definir `enable_caching=False`. + +### Autenticação por Par de Chaves + +Além de autenticação por senha, a ferramenta também suporta autenticação por par de chaves para maior segurança: + +```python Code +config = SnowflakeConfig( + account="your_account", + user="your_username", + private_key_path="/path/to/your/private/key.p8", + warehouse="COMPUTE_WH", + database="your_database", + snowflake_schema="your_schema" +) +``` + +## Tratamento de Erros + +O `SnowflakeSearchTool` inclui uma gestão abrangente de erros para situações comuns no Snowflake: + +- Falhas de conexão +- Timeout de consultas +- Erros de autenticação +- Erros de banco de dados e schema + +Quando um erro ocorrer, a ferramenta tentará repetir a operação (se estiver configurado) e fornecerá informações detalhadas sobre o erro. + +## Conclusão + +O `SnowflakeSearchTool` oferece uma maneira poderosa de integrar data warehouses Snowflake com agentes CrewAI. Com recursos como pool de conexões, tentativas automáticas e cache de consultas, ele possibilita acesso eficiente e confiável aos dados empresariais. Esta ferramenta é particularmente útil para tarefas de análise de dados, relatórios e inteligência de negócios que demandam acesso a dados estruturados armazenados no Snowflake. \ No newline at end of file diff --git a/docs/pt-BR/tools/database-data/weaviatevectorsearchtool.mdx b/docs/pt-BR/tools/database-data/weaviatevectorsearchtool.mdx new file mode 100644 index 000000000..afe1defd4 --- /dev/null +++ b/docs/pt-BR/tools/database-data/weaviatevectorsearchtool.mdx @@ -0,0 +1,162 @@ +--- +title: Busca Vetorial Weaviate +description: O `WeaviateVectorSearchTool` foi projetado para buscar documentos semanticamente similares em um banco de dados vetorial Weaviate. +icon: network-wired +--- + +## Visão Geral + +O `WeaviateVectorSearchTool` foi especificamente desenvolvido para realizar buscas semânticas em documentos armazenados em um banco de dados vetorial Weaviate. Essa ferramenta permite encontrar documentos semanticamente similares a uma determinada consulta, aproveitando o poder das embeddings vetoriais para resultados de busca mais precisos e contextualmente relevantes. + +[Weaviate](https://weaviate.io/) é um banco de dados vetorial que armazena e consulta embeddings vetoriais, possibilitando recursos de busca semântica. + +## Instalação + +Para incorporar esta ferramenta ao seu projeto, é necessário instalar o cliente Weaviate: + +```shell +uv add weaviate-client +``` + +## Etapas para Começar + +Para utilizar efetivamente o `WeaviateVectorSearchTool`, siga as etapas abaixo: + +1. **Instalação dos Pacotes**: Confirme que os pacotes `crewai[tools]` e `weaviate-client` estão instalados em seu ambiente Python. +2. **Configuração do Weaviate**: Configure um cluster Weaviate. Você pode seguir as instruções na [documentação do Weaviate](https://weaviate.io/developers/wcs/manage-clusters/connect). +3. **Chaves de API**: Obtenha a URL do seu cluster Weaviate e a chave de API correspondente. +4. **Chave de API da OpenAI**: Certifique-se de que você tenha uma chave de API da OpenAI definida nas variáveis de ambiente como `OPENAI_API_KEY`. + +## Exemplo + +O exemplo a seguir demonstra como inicializar a ferramenta e executar uma busca: + +```python Code +from crewai_tools import WeaviateVectorSearchTool + +# Inicializar a ferramenta +tool = WeaviateVectorSearchTool( + collection_name='example_collections', + limit=3, + weaviate_cluster_url="https://your-weaviate-cluster-url.com", + weaviate_api_key="your-weaviate-api-key", +) + +@agent +def search_agent(self) -> Agent: + ''' + Este agente utiliza o WeaviateVectorSearchTool para buscar + documentos semanticamente similares em um banco de dados vetorial Weaviate. + ''' + return Agent( + config=self.agents_config["search_agent"], + tools=[tool] + ) +``` + +## Parâmetros + +O `WeaviateVectorSearchTool` aceita os seguintes parâmetros: + +- **collection_name**: Obrigatório. O nome da coleção a ser pesquisada. +- **weaviate_cluster_url**: Obrigatório. A URL do cluster Weaviate. +- **weaviate_api_key**: Obrigatório. A chave de API para o cluster Weaviate. +- **limit**: Opcional. O número de resultados a serem retornados. O padrão é `3`. +- **vectorizer**: Opcional. O vetorizador a ser utilizado. Se não for informado, será utilizado o `text2vec_openai` com o modelo `nomic-embed-text`. +- **generative_model**: Opcional. O modelo generativo a ser utilizado. Se não for informado, será utilizado o `gpt-4o` da OpenAI. + +## Configuração Avançada + +Você pode personalizar o vetorizador e o modelo generativo utilizados pela ferramenta: + +```python Code +from crewai_tools import WeaviateVectorSearchTool +from weaviate.classes.config import Configure + +# Configurar modelo personalizado para vetorizador e modelo generativo +tool = WeaviateVectorSearchTool( + collection_name='example_collections', + limit=3, + vectorizer=Configure.Vectorizer.text2vec_openai(model="nomic-embed-text"), + generative_model=Configure.Generative.openai(model="gpt-4o-mini"), + weaviate_cluster_url="https://your-weaviate-cluster-url.com", + weaviate_api_key="your-weaviate-api-key", +) +``` + +## Pré-carregando Documentos + +Você pode pré-carregar seu banco de dados Weaviate com documentos antes de utilizar a ferramenta: + +```python Code +import os +from crewai_tools import WeaviateVectorSearchTool +import weaviate +from weaviate.classes.init import Auth + +# Conectar ao Weaviate +client = weaviate.connect_to_weaviate_cloud( + cluster_url="https://your-weaviate-cluster-url.com", + auth_credentials=Auth.api_key("your-weaviate-api-key"), + headers={"X-OpenAI-Api-Key": "your-openai-api-key"} +) + +# Obter ou criar coleção +test_docs = client.collections.get("example_collections") +if not test_docs: + test_docs = client.collections.create( + name="example_collections", + vectorizer_config=Configure.Vectorizer.text2vec_openai(model="nomic-embed-text"), + generative_config=Configure.Generative.openai(model="gpt-4o"), + ) + +# Carregar documentos +docs_to_load = os.listdir("knowledge") +with test_docs.batch.dynamic() as batch: + for d in docs_to_load: + with open(os.path.join("knowledge", d), "r") as f: + content = f.read() + batch.add_object( + { + "content": content, + "year": d.split("_")[0], + } + ) + +# Inicializar a ferramenta +tool = WeaviateVectorSearchTool( + collection_name='example_collections', + limit=3, + weaviate_cluster_url="https://your-weaviate-cluster-url.com", + weaviate_api_key="your-weaviate-api-key", +) +``` + +## Exemplo de Integração com Agente + +Veja como integrar o `WeaviateVectorSearchTool` com um agente CrewAI: + +```python Code +from crewai import Agent +from crewai_tools import WeaviateVectorSearchTool + +# Inicializar a ferramenta +weaviate_tool = WeaviateVectorSearchTool( + collection_name='example_collections', + limit=3, + weaviate_cluster_url="https://your-weaviate-cluster-url.com", + weaviate_api_key="your-weaviate-api-key", +) + +# Criar um agente com a ferramenta +rag_agent = Agent( + name="rag_agent", + role="Você é um assistente útil que pode responder perguntas com a ajuda do WeaviateVectorSearchTool.", + llm="gpt-4o-mini", + tools=[weaviate_tool], +) +``` + +## Conclusão + +O `WeaviateVectorSearchTool` fornece uma maneira poderosa de buscar documentos semanticamente similares em um banco de dados vetorial Weaviate. Ao utilizar embeddings vetoriais, ele permite resultados de busca mais precisos e relevantes em termos de contexto, quando comparado a buscas tradicionais baseadas em palavras-chave. Essa ferramenta é especialmente útil para aplicações que precisam encontrar informações a partir do significado e não apenas de correspondências exatas. \ No newline at end of file diff --git a/docs/pt-BR/tools/file-document/csvsearchtool.mdx b/docs/pt-BR/tools/file-document/csvsearchtool.mdx new file mode 100644 index 000000000..55e89661a --- /dev/null +++ b/docs/pt-BR/tools/file-document/csvsearchtool.mdx @@ -0,0 +1,77 @@ +--- +title: Busca RAG em CSV +description: O `CSVSearchTool` é uma poderosa ferramenta RAG (Geração com Recuperação Aprimorada) projetada para buscas semânticas no conteúdo de arquivos CSV. +icon: file-csv +--- + +# `CSVSearchTool` + + + **Experimental**: Ainda estamos trabalhando na melhoria das ferramentas, portanto podem ocorrer comportamentos inesperados ou mudanças futuras. + + +## Descrição + +Esta ferramenta é utilizada para realizar buscas RAG (Geração com Recuperação Aprimorada) no conteúdo de um arquivo CSV. Ela permite que usuários façam buscas semânticas por consultas no conteúdo de um arquivo CSV especificado. +Este recurso é particularmente útil para extrair informações de grandes datasets CSV, em que métodos de busca tradicionais poderiam ser ineficientes. Todas as ferramentas com "Search" no nome, incluindo o CSVSearchTool, +são ferramentas RAG projetadas para busca em diferentes fontes de dados. + +## Instalação + +Instale o pacote crewai_tools + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo + +```python Code +from crewai_tools import CSVSearchTool + +# Inicialize a ferramenta com um arquivo CSV específico. +# Esta configuração permite que o agente busque somente no arquivo CSV fornecido. +tool = CSVSearchTool(csv='path/to/your/csvfile.csv') + +# OU + +# Inicialize a ferramenta sem um arquivo CSV específico. +# O agente precisará informar o caminho do CSV em tempo de execução. +tool = CSVSearchTool() +``` + +## Argumentos + +Os seguintes parâmetros podem ser utilizados para personalizar o comportamento do `CSVSearchTool`: + +| Argumento | Tipo | Descrição | +|:---------------|:----------|:----------------------------------------------------------------------------------------------------------------------------------| +| **csv** | `string` | _Opcional_. O caminho para o arquivo CSV que você deseja buscar. Este é um argumento obrigatório se a ferramenta for inicializada sem um arquivo CSV específico; caso contrário, é opcional. | + +## Modelo e embeddings personalizados + +Por padrão, a ferramenta utiliza OpenAI tanto para embeddings quanto para sumarização. Para personalizar o modelo, você pode usar um dicionário de configuração como segue: + +```python Code +tool = CSVSearchTool( + config=dict( + llm=dict( + provider="ollama", # ou google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", # ou openai, ollama, ... + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/file-document/directoryreadtool.mdx b/docs/pt-BR/tools/file-document/directoryreadtool.mdx new file mode 100644 index 000000000..39d6e5137 --- /dev/null +++ b/docs/pt-BR/tools/file-document/directoryreadtool.mdx @@ -0,0 +1,53 @@ +--- +title: Leitura de Diretório +description: O `DirectoryReadTool` é uma poderosa utilidade projetada para fornecer uma listagem abrangente do conteúdo de diretórios. +icon: folder-tree +--- + +# `DirectoryReadTool` + + + Ainda estamos trabalhando para melhorar as ferramentas, então pode haver comportamentos inesperados ou alterações no futuro. + + +## Descrição + +O DirectoryReadTool é uma poderosa utilidade projetada para fornecer uma listagem abrangente do conteúdo de diretórios. +Ele pode navegar recursivamente pelo diretório especificado, oferecendo aos usuários uma enumeração detalhada de todos os arquivos, incluindo aqueles que estão dentro de subdiretórios. +Essa ferramenta é fundamental para tarefas que exigem um inventário completo das estruturas de diretórios ou para validar a organização de arquivos em diretórios. + +## Instalação + +Para utilizar o DirectoryReadTool em seu projeto, instale o pacote `crewai_tools`. Se este pacote ainda não faz parte do seu ambiente, você pode instalá-lo usando o pip com o comando abaixo: + +```shell +pip install 'crewai[tools]' +``` + +Esse comando instala a versão mais recente do pacote `crewai_tools`, permitindo o acesso ao DirectoryReadTool, entre outras utilidades. + +## Exemplo + +Empregar o DirectoryReadTool é simples. O snippet de código a seguir demonstra como configurá-lo e usar a ferramenta para listar o conteúdo de um diretório especificado: + +```python Code +from crewai_tools import DirectoryReadTool + +# Initialize the tool so the agent can read any directory's content +# it learns about during execution +tool = DirectoryReadTool() + +# OR + +# Initialize the tool with a specific directory, +# so the agent can only read the content of the specified directory +tool = DirectoryReadTool(directory='/path/to/your/directory') +``` + +## Argumentos + +Os seguintes parâmetros podem ser usados para personalizar o comportamento do `DirectoryReadTool`: + +| Argumento | Tipo | Descrição | +|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------| +| **directory** | `string` | _Opcional_. Um argumento que especifica o caminho para o diretório cujo conteúdo você deseja listar. Aceita caminhos absolutos e relativos, direcionando a ferramenta para o diretório desejado para a listagem do conteúdo. | \ No newline at end of file diff --git a/docs/pt-BR/tools/file-document/directorysearchtool.mdx b/docs/pt-BR/tools/file-document/directorysearchtool.mdx new file mode 100644 index 000000000..bb60cd287 --- /dev/null +++ b/docs/pt-BR/tools/file-document/directorysearchtool.mdx @@ -0,0 +1,67 @@ +--- +title: Busca RAG em Diretório +description: O `DirectorySearchTool` é uma poderosa ferramenta RAG (Retrieval-Augmented Generation) desenvolvida para buscas semânticas no conteúdo de um diretório. +icon: address-book +--- + +# `DirectorySearchTool` + + + **Experimental**: O DirectorySearchTool está em desenvolvimento contínuo. As funcionalidades e recursos podem evoluir, e comportamentos inesperados podem ocorrer enquanto aprimoramos a ferramenta. + + +## Descrição + +O DirectorySearchTool permite a busca semântica dentro do conteúdo de diretórios especificados, aproveitando a metodologia de Recuperação com Geração Aumentada (RAG) para uma navegação eficiente entre arquivos. Projetada para flexibilidade, a ferramenta possibilita que usuários especifiquem dinamicamente os diretórios de busca em tempo de execução ou definam um diretório fixo durante a configuração inicial. + +## Instalação + +Para utilizar o DirectorySearchTool, comece instalando o pacote crewai_tools. Execute o seguinte comando no seu terminal: + +```shell +pip install 'crewai[tools]' +``` + +## Inicialização e Uso + +Importe o DirectorySearchTool do pacote `crewai_tools` para começar. Você pode inicializar a ferramenta sem especificar um diretório, permitindo definir o diretório de busca em tempo de execução. Alternativamente, a ferramenta pode ser inicializada já com um diretório predefinido. + +```python Code +from crewai_tools import DirectorySearchTool + +# Para especificação dinâmica de diretório em tempo de execução +tool = DirectorySearchTool() + +# Para buscas em diretório fixo +tool = DirectorySearchTool(directory='/path/to/directory') +``` + +## Argumentos + +- `directory`: Um argumento do tipo string que especifica o diretório de busca. Este parâmetro é opcional durante a inicialização, mas obrigatório para buscas caso não tenha sido definido inicialmente. + +## Modelo Personalizado e Embeddings + +O DirectorySearchTool utiliza OpenAI para embeddings e sumarização por padrão. As opções de personalização dessas configurações incluem a alteração do provedor de modelo e configurações, ampliando a flexibilidade para usuários avançados. + +```python Code +tool = DirectorySearchTool( + config=dict( + llm=dict( + provider="ollama", # As opções incluem ollama, google, anthropic, llama2 e mais + config=dict( + model="llama2", + # Configurações adicionais aqui + ), + ), + embedder=dict( + provider="google", # ou openai, ollama, ... + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/file-document/docxsearchtool.mdx b/docs/pt-BR/tools/file-document/docxsearchtool.mdx new file mode 100644 index 000000000..7038038d0 --- /dev/null +++ b/docs/pt-BR/tools/file-document/docxsearchtool.mdx @@ -0,0 +1,79 @@ +--- +title: Pesquisa RAG em DOCX +description: A `DOCXSearchTool` é uma ferramenta RAG projetada para busca semântica em documentos DOCX. +icon: file-word +--- + +# `DOCXSearchTool` + + + Ainda estamos trabalhando na melhoria das ferramentas, portanto pode haver comportamentos inesperados ou alterações no futuro. + + +## Descrição + +A `DOCXSearchTool` é uma ferramenta RAG desenvolvida para buscas semânticas dentro de documentos DOCX. +Ela permite que os usuários pesquisem e extraiam informações relevantes de arquivos DOCX de forma eficiente, utilizando buscas baseadas em consultas. +Esta ferramenta é inestimável para análise de dados, gestão da informação e tarefas de pesquisa, +otimizando o processo de encontrar informações específicas em grandes coleções de documentos. + +## Instalação + +Instale o pacote crewai_tools executando o seguinte comando no seu terminal: + +```shell +uv pip install docx2txt 'crewai[tools]' +``` + +## Exemplo + +O exemplo a seguir demonstra a inicialização da DOCXSearchTool para buscar dentro do conteúdo de qualquer arquivo DOCX ou com o caminho de um arquivo DOCX específico. + +```python Code +from crewai_tools import DOCXSearchTool + +# Inicialize a ferramenta para buscar dentro do conteúdo de qualquer arquivo DOCX +tool = DOCXSearchTool() + +# OU + +# Inicialize a ferramenta com um arquivo DOCX específico, +# assim o agente só poderá buscar dentro do conteúdo do arquivo DOCX especificado +tool = DOCXSearchTool(docx='path/to/your/document.docx') +``` + +## Argumentos + +Os seguintes parâmetros podem ser usados para customizar o comportamento da `DOCXSearchTool`: + +| Argumento | Tipo | Descrição | +|:---------------|:----------|:------------------------------------------------------------------------------------------------------------------------------------| +| **docx** | `string` | _Opcional_. Um argumento que especifica o caminho para o arquivo DOCX que você deseja pesquisar. Se não for fornecido durante a inicialização, a ferramenta permite a especificação posterior do caminho de qualquer arquivo DOCX para busca. | + +## Modelo e embeddings personalizados + +Por padrão, a ferramenta utiliza o OpenAI tanto para embeddings quanto para sumarização. Para customizar o modelo, você pode usar um dicionário de configuração como no exemplo: + +```python Code +tool = DOCXSearchTool( + config=dict( + llm=dict( + provider="ollama", # ou google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", # ou openai, ollama, ... + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/file-document/filereadtool.mdx b/docs/pt-BR/tools/file-document/filereadtool.mdx new file mode 100644 index 000000000..f2bf10506 --- /dev/null +++ b/docs/pt-BR/tools/file-document/filereadtool.mdx @@ -0,0 +1,44 @@ +--- +title: Leitura de Arquivo +description: O `FileReadTool` foi desenvolvido para ler arquivos do sistema de arquivos local. +icon: folders +--- + +## Visão Geral + + + Ainda estamos trabalhando para melhorar as ferramentas, portanto pode haver comportamentos inesperados ou alterações no futuro. + + +O FileReadTool representa conceitualmente um conjunto de funcionalidades dentro do pacote crewai_tools voltadas para facilitar a leitura e a recuperação de conteúdo de arquivos. +Esse conjunto inclui ferramentas para processar arquivos de texto em lote, ler arquivos de configuração em tempo de execução e importar dados para análise. +Ele suporta uma variedade de formatos de arquivo baseados em texto, como `.txt`, `.csv`, `.json` e outros. Dependendo do tipo de arquivo, o conjunto oferece funcionalidades especializadas, +como converter conteúdo JSON em um dicionário Python para facilitar o uso. + +## Instalação + +Para utilizar as funcionalidades anteriormente atribuídas ao FileReadTool, instale o pacote crewai_tools: + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo de Uso + +Para começar a usar o FileReadTool: + +```python Code +from crewai_tools import FileReadTool + +# Inicialize a ferramenta para ler quaisquer arquivos que os agentes conhecem ou informe o caminho para +file_read_tool = FileReadTool() + +# OU + +# Inicialize a ferramenta com um caminho de arquivo específico, assim o agente poderá ler apenas o conteúdo do arquivo especificado +file_read_tool = FileReadTool(file_path='path/to/your/file.txt') +``` + +## Argumentos + +- `file_path`: O caminho para o arquivo que você deseja ler. Aceita caminhos absolutos e relativos. Certifique-se de que o arquivo exista e de que você tenha as permissões necessárias para acessá-lo. \ No newline at end of file diff --git a/docs/pt-BR/tools/file-document/filewritetool.mdx b/docs/pt-BR/tools/file-document/filewritetool.mdx new file mode 100644 index 000000000..18f6053e8 --- /dev/null +++ b/docs/pt-BR/tools/file-document/filewritetool.mdx @@ -0,0 +1,50 @@ +--- +title: Escrita de Arquivo +description: O `FileWriterTool` foi projetado para escrever conteúdo em arquivos. +icon: file-pen +--- + +# `FileWriterTool` + +## Descrição + +O `FileWriterTool` é um componente do pacote crewai_tools, projetado para simplificar o processo de escrita de conteúdo em arquivos com compatibilidade multiplataforma (Windows, Linux, macOS). +É particularmente útil em cenários como geração de relatórios, salvamento de logs, criação de arquivos de configuração e mais. +Essa ferramenta lida com diferenças de caminhos entre sistemas operacionais, suporta codificação UTF-8 e cria diretórios automaticamente caso eles não existam, facilitando a organização da sua saída de forma confiável em diferentes plataformas. + +## Instalação + +Instale o pacote crewai_tools para utilizar o `FileWriterTool` em seus projetos: + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo + +Para começar a usar o `FileWriterTool`: + +```python Code +from crewai_tools import FileWriterTool + +# Inicialize a ferramenta +file_writer_tool = FileWriterTool() + +# Escreva conteúdo em um arquivo em um diretório especificado +result = file_writer_tool._run('example.txt', 'This is a test content.', 'test_directory') +print(result) +``` + +## Argumentos + +- `filename`: O nome do arquivo que você deseja criar ou sobrescrever. +- `content`: O conteúdo a ser escrito no arquivo. +- `directory` (opcional): O caminho para o diretório onde o arquivo será criado. Por padrão, utiliza o diretório atual (`.`). Se o diretório não existir, ele será criado. + +## Conclusão + +Ao integrar o `FileWriterTool` aos seus crews, os agentes podem escrever conteúdo em arquivos de forma confiável em diferentes sistemas operacionais. +Esta ferramenta é essencial para tarefas que exigem salvamento de dados de saída, criação de sistemas de arquivos estruturados e manipulação de operações de arquivos multiplataforma. +É especialmente recomendada para usuários do Windows que possam enfrentar problemas ao escrever arquivos com as operações padrão do Python. + +Seguindo as orientações de configuração e uso fornecidas, incorporar essa ferramenta em projetos é simples e garante um comportamento consistente de escrita de arquivos em todas as plataformas. \ No newline at end of file diff --git a/docs/pt-BR/tools/file-document/jsonsearchtool.mdx b/docs/pt-BR/tools/file-document/jsonsearchtool.mdx new file mode 100644 index 000000000..290566469 --- /dev/null +++ b/docs/pt-BR/tools/file-document/jsonsearchtool.mdx @@ -0,0 +1,75 @@ +--- +title: Busca JSON RAG +description: O `JSONSearchTool` foi projetado para buscar arquivos JSON e retornar os resultados mais relevantes. +icon: file-code +--- + +# `JSONSearchTool` + + + O JSONSearchTool está atualmente em fase experimental. Isso significa que a ferramenta + está em desenvolvimento ativo, e os usuários podem encontrar comportamentos inesperados ou + alterações. Incentivamos fortemente o envio de feedback sobre quaisquer problemas ou sugestões de + melhorias. + + +## Descrição + +O JSONSearchTool foi projetado para facilitar buscas eficientes e precisas dentro do conteúdo de arquivos JSON. Ele utiliza um mecanismo de busca RAG (Retrieve and Generate), permitindo que os usuários especifiquem um caminho JSON para buscas direcionadas dentro de um arquivo JSON específico. Essa capacidade melhora significativamente a precisão e relevância dos resultados de busca. + +## Instalação + +Para instalar o JSONSearchTool, utilize o seguinte comando pip: + +```shell +pip install 'crewai[tools]' +``` + +## Exemplos de Uso + +Aqui estão exemplos atualizados de como utilizar o JSONSearchTool de forma eficaz para buscar dentro de arquivos JSON. Esses exemplos consideram a implementação e padrões de uso atuais identificados na base de código. + +```python Code +from crewai_tools import JSONSearchTool + +# Busca geral em conteúdo JSON +# Esta abordagem é adequada quando o caminho JSON já é conhecido ou pode ser identificado dinamicamente. +tool = JSONSearchTool() + +# Restringindo a busca a um arquivo JSON específico +# Use este método de inicialização quando desejar limitar o escopo de busca a um arquivo específico. +tool = JSONSearchTool(json_path='./path/to/your/file.json') +``` + +## Argumentos + +- `json_path` (str, opcional): Especifica o caminho para o arquivo JSON a ser buscado. Este argumento não é obrigatório se a ferramenta for inicializada para uma busca geral. Quando fornecido, limita a busca ao arquivo JSON especificado. + +## Opções de Configuração + +O JSONSearchTool oferece ampla personalização através de um dicionário de configuração. Isso permite que os usuários selecionem diferentes modelos para embeddings e sumarização conforme suas necessidades. + +```python Code +tool = JSONSearchTool( + config={ + "llm": { + "provider": "ollama", # Outras opções incluem google, openai, anthropic, llama2, etc. + "config": { + "model": "llama2", + # Configurações opcionais adicionais podem ser especificadas aqui. + # temperature=0.5, + # top_p=1, + # stream=true, + }, + }, + "embedding_model": { + "provider": "google", # ou openai, ollama, ... + "config": { + "model": "models/embedding-001", + "task_type": "retrieval_document", + # Mais opções de personalização podem ser adicionadas aqui. + }, + }, + } +) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/file-document/mdxsearchtool.mdx b/docs/pt-BR/tools/file-document/mdxsearchtool.mdx new file mode 100644 index 000000000..10fc99d91 --- /dev/null +++ b/docs/pt-BR/tools/file-document/mdxsearchtool.mdx @@ -0,0 +1,73 @@ +--- +title: Pesquisa MDX RAG +description: O `MDXSearchTool` foi projetado para pesquisar arquivos MDX e retornar os resultados mais relevantes. +icon: markdown +--- + +# `MDXSearchTool` + + + O MDXSearchTool está em desenvolvimento contínuo. Recursos podem ser adicionados ou removidos, e a funcionalidade pode mudar de forma imprevisível à medida que refinamos a ferramenta. + + +## Descrição + +A Ferramenta de Pesquisa MDX é um componente do pacote `crewai_tools` focado em facilitar a extração avançada de dados do markdown. Ela permite que usuários pesquisem e extraiam informações relevantes de arquivos MD utilizando buscas baseadas em consulta. Esta ferramenta é indispensável para análise de dados, gestão de informações e tarefas de pesquisa, agilizando o processo de encontrar informações específicas em grandes coleções de documentos. + +## Instalação + +Antes de utilizar a Ferramenta de Pesquisa MDX, certifique-se de que o pacote `crewai_tools` está instalado. Caso não esteja, você pode instalá-lo com o comando abaixo: + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo de Uso + +Para utilizar a Ferramenta de Pesquisa MDX, primeiro defina as variáveis de ambiente necessárias. Em seguida, integre a ferramenta ao seu projeto crewAI para começar sua pesquisa de mercado. Veja abaixo um exemplo básico de como fazer isso: + +```python Code +from crewai_tools import MDXSearchTool + +# Inicialize a ferramenta para pesquisar qualquer conteúdo MDX que ela conheça durante a execução +tool = MDXSearchTool() + +# OU + +# Inicialize a ferramenta com um caminho específico para o arquivo MDX, realizando buscas exclusivamente neste documento +tool = MDXSearchTool(mdx='path/to/your/document.mdx') +``` + +## Parâmetros + +- mdx: **Opcional**. Especifica o caminho do arquivo MDX para pesquisa. Pode ser informado durante a inicialização. + +## Personalização do Modelo e Embeddings + +A ferramenta utiliza, por padrão, o OpenAI para embeddings e sumarização. Para personalizar, utilize um dicionário de configuração conforme exemplo abaixo: + +```python Code +tool = MDXSearchTool( + config=dict( + llm=dict( + provider="ollama", # As opções incluem google, openai, anthropic, llama2, etc. + config=dict( + model="llama2", + # Parâmetros opcionais podem ser incluídos aqui. + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", # ou openai, ollama, ... + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # Um título opcional para os embeddings pode ser adicionado aqui. + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/file-document/overview.mdx b/docs/pt-BR/tools/file-document/overview.mdx new file mode 100644 index 000000000..ba859098d --- /dev/null +++ b/docs/pt-BR/tools/file-document/overview.mdx @@ -0,0 +1,88 @@ +--- +title: "Visão Geral" +description: "Leia, escreva e pesquise em diversos formatos de arquivos com as ferramentas de processamento de documentos do CrewAI" +icon: "face-smile" +--- + +Estas ferramentas permitem que seus agentes trabalhem com diversos formatos e tipos de documentos. De leitura de PDFs ao processamento de dados em JSON, essas ferramentas atendem a todas as suas necessidades de processamento de documentos. + +## **Ferramentas Disponíveis** + + + + Leia conteúdo de qualquer tipo de arquivo, incluindo texto, markdown e mais. + + + + Escreva conteúdo em arquivos, crie novos documentos e salve dados processados. + + + + Pesquise e extraia conteúdo de texto de documentos PDF de forma eficiente. + + + + Pesquise em documentos do Microsoft Word e extraia conteúdo relevante. + + + + Faça a análise e pesquisa em arquivos JSON com recursos avançados de consulta. + + + + Processe e pesquise em arquivos CSV, extraia linhas e colunas específicas. + + + + Analise arquivos XML e pesquise elementos e atributos específicos. + + + + Pesquise em arquivos MDX e extraia conteúdo de documentações. + + + + Pesquise em arquivos de texto simples com recursos de busca por padrões. + + + + Pesquise arquivos e pastas dentro de estruturas de diretórios. + + + + Leia e liste conteúdos de diretórios, estruturas de arquivos e metadados. + + + +## **Casos de Uso Comuns** + +- **Processamento de Documentos**: Extraia e analise conteúdo de vários formatos de arquivos +- **Importação de Dados**: Leia dados estruturados de arquivos CSV, JSON e XML +- **Busca por Conteúdo**: Encontre informações específicas em grandes coleções de documentos +- **Gerenciamento de Arquivos**: Organize e manipule arquivos e diretórios +- **Exportação de Dados**: Salve os resultados processados em vários formatos de arquivo + +## **Exemplo Rápido de Início** + +```python +from crewai_tools import FileReadTool, PDFSearchTool, JSONSearchTool + +# Create tools +file_reader = FileReadTool() +pdf_searcher = PDFSearchTool() +json_processor = JSONSearchTool() + +# Add to your agent +agent = Agent( + role="Document Analyst", + tools=[file_reader, pdf_searcher, json_processor], + goal="Process and analyze various document types" +) +``` + +## **Dicas para Processamento de Documentos** + +- **Permissões de Arquivo**: Certifique-se de que seu agente possui as permissões adequadas de leitura/escrita +- **Arquivos Grandes**: Considere dividir documentos muito grandes em partes menores +- **Suporte de Formatos**: Consulte a documentação da ferramenta para saber quais formatos de arquivos são suportados +- **Tratamento de Erros**: Implemente tratamento de erros adequado para arquivos corrompidos ou inacessíveis diff --git a/docs/pt-BR/tools/file-document/pdfsearchtool.mdx b/docs/pt-BR/tools/file-document/pdfsearchtool.mdx new file mode 100644 index 000000000..bb03e3618 --- /dev/null +++ b/docs/pt-BR/tools/file-document/pdfsearchtool.mdx @@ -0,0 +1,71 @@ +--- +title: Busca RAG em PDF +description: O `PDFSearchTool` é projetado para pesquisar arquivos PDF e retornar os resultados mais relevantes. +icon: file-pdf +--- + +# `PDFSearchTool` + + + Ainda estamos trabalhando para melhorar as ferramentas, então pode haver comportamentos inesperados ou mudanças futuras. + + +## Descrição + +O PDFSearchTool é uma ferramenta RAG projetada para buscas semânticas dentro do conteúdo de PDFs. Ela permite inserir uma consulta de busca e um documento PDF, aproveitando técnicas avançadas de busca para encontrar conteúdos relevantes de forma eficiente. +Essa capacidade a torna especialmente útil para extrair informações específicas de arquivos PDF grandes rapidamente. + +## Instalação + +Para começar a usar o PDFSearchTool, primeiro, garanta que o pacote crewai_tools está instalado com o seguinte comando: + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo +Veja como utilizar o PDFSearchTool para buscar dentro de um documento PDF: + +```python Code +from crewai_tools import PDFSearchTool + +# Inicialize a ferramenta permitindo buscas em qualquer conteúdo PDF caso o caminho seja informado durante a execução +tool = PDFSearchTool() + +# OU + +# Inicialize a ferramenta com um caminho PDF específico para buscas exclusivas naquele documento +tool = PDFSearchTool(pdf='path/to/your/document.pdf') +``` + +## Argumentos + +- `pdf`: **Opcional** O caminho do PDF para busca. Pode ser fornecido na inicialização ou nos argumentos do método `run`. Caso seja fornecido na inicialização, a ferramenta confinará suas buscas ao documento especificado. + +## Modelo e embeddings personalizados + +Por padrão, a ferramenta utiliza OpenAI tanto para embeddings quanto para sumarização. Para personalizar o modelo, você pode usar um dicionário de configuração como no exemplo abaixo: + +```python Code +tool = PDFSearchTool( + config=dict( + llm=dict( + provider="ollama", # ou google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", # ou openai, ollama, ... + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/file-document/txtsearchtool.mdx b/docs/pt-BR/tools/file-document/txtsearchtool.mdx new file mode 100644 index 000000000..4cfad823b --- /dev/null +++ b/docs/pt-BR/tools/file-document/txtsearchtool.mdx @@ -0,0 +1,80 @@ +--- +title: Pesquisa TXT RAG +description: O `TXTSearchTool` foi projetado para realizar uma busca RAG (Geração Aumentada por Recuperação) dentro do conteúdo de um arquivo de texto. +icon: file-lines +--- + +## Visão Geral + + + Ainda estamos trabalhando para melhorar as ferramentas, por isso pode haver comportamentos inesperados ou mudanças no futuro. + + +Esta ferramenta é utilizada para realizar uma busca RAG (Geração Aumentada por Recuperação) dentro do conteúdo de um arquivo de texto. +Ela permite uma busca semântica de uma consulta dentro do conteúdo de um arquivo de texto especificado, +tornando-se um recurso valioso para extrair rapidamente informações ou encontrar seções específicas do texto com base na consulta fornecida. + +## Instalação + +Para usar o `TXTSearchTool`, primeiro é necessário instalar o pacote `crewai_tools`. +Isso pode ser feito usando o pip, um gerenciador de pacotes para Python. +Abra seu terminal ou prompt de comando e digite o seguinte comando: + +```shell +pip install 'crewai[tools]' +``` + +Este comando fará o download e instalará o TXTSearchTool junto com todas as dependências necessárias. + +## Exemplo + +O exemplo a seguir demonstra como usar o TXTSearchTool para pesquisar dentro de um arquivo de texto. +Este exemplo mostra tanto a inicialização da ferramenta com um arquivo de texto específico quanto a pesquisa subsequente dentro do conteúdo desse arquivo. + +```python Code +from crewai_tools import TXTSearchTool + +# Inicialize a ferramenta para pesquisar no conteúdo de qualquer arquivo de texto +# que o agente aprender durante sua execução +tool = TXTSearchTool() + +# OU + +# Inicialize a ferramenta com um arquivo de texto específico, +# para que o agente possa pesquisar dentro do conteúdo desse arquivo de texto +tool = TXTSearchTool(txt='path/to/text/file.txt') +``` + +## Argumentos +- `txt` (str): **Opcional**. O caminho para o arquivo de texto que você deseja pesquisar. +Este argumento só é necessário se a ferramenta não foi inicializada com um arquivo de texto específico; +caso contrário, a pesquisa será realizada no arquivo de texto fornecido inicialmente. + +## Modelo e embeddings personalizados + +Por padrão, a ferramenta utiliza o OpenAI tanto para embeddings quanto para sumarização. +Para personalizar o modelo, você pode usar um dicionário de configuração como o exemplo a seguir: + +```python Code +tool = TXTSearchTool( + config=dict( + llm=dict( + provider="ollama", # ou google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", # ou openai, ollama, ... + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/file-document/xmlsearchtool.mdx b/docs/pt-BR/tools/file-document/xmlsearchtool.mdx new file mode 100644 index 000000000..c4207e987 --- /dev/null +++ b/docs/pt-BR/tools/file-document/xmlsearchtool.mdx @@ -0,0 +1,77 @@ +--- +title: Busca RAG em XML +description: O `XMLSearchTool` foi projetado para realizar uma busca RAG (Geração Aumentada por Recuperação) dentro do conteúdo de um arquivo XML. +icon: file-xml +--- + +# `XMLSearchTool` + + + Ainda estamos trabalhando na melhoria das ferramentas, então pode haver comportamentos inesperados ou mudanças no futuro. + + +## Descrição + +O XMLSearchTool é uma ferramenta RAG de ponta, desenvolvida para realizar buscas semânticas em arquivos XML. +Ideal para usuários que precisam analisar e extrair informações do conteúdo XML de forma eficiente, esta ferramenta permite inserir uma consulta de busca e um caminho opcional para o arquivo XML. +Ao especificar um caminho de arquivo XML, o usuário pode direcionar sua busca de forma mais precisa ao conteúdo daquele arquivo, obtendo assim resultados mais relevantes. + +## Instalação + +Para começar a usar o XMLSearchTool, é necessário instalar primeiro o pacote crewai_tools. Isso pode ser feito facilmente com o seguinte comando: + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo + +Aqui estão dois exemplos demonstrando como usar o XMLSearchTool. +O primeiro exemplo mostra a busca dentro de um arquivo XML específico, enquanto o segundo exemplo ilustra como iniciar uma busca sem definir previamente um caminho XML, oferecendo flexibilidade no escopo da busca. + +```python Code +from crewai_tools import XMLSearchTool + +# Permite que agentes busquem no conteúdo de qualquer arquivo XML +# conforme aprendem seus caminhos durante a execução +tool = XMLSearchTool() + +# OU + +# Inicializa a ferramenta com um caminho específico para arquivo XML +# para busca exclusiva dentro desse documento +tool = XMLSearchTool(xml='path/to/your/xmlfile.xml') +``` + +## Argumentos + +- `xml`: Este é o caminho para o arquivo XML que você deseja buscar. +Este parâmetro é opcional durante a inicialização da ferramenta, mas deve ser fornecido ou na inicialização ou como parte dos argumentos do método `run` para executar a busca. + +## Modelo customizado e embeddings + +Por padrão, a ferramenta utiliza a OpenAI tanto para embeddings quanto para sumarização. Para personalizar o modelo, você pode usar um dicionário de configuração conforme o exemplo a seguir: + +```python Code +tool = XMLSearchTool( + config=dict( + llm=dict( + provider="ollama", # ou google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", # ou openai, ollama, ... + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/overview.mdx b/docs/pt-BR/tools/overview.mdx new file mode 100644 index 000000000..4265d04c7 --- /dev/null +++ b/docs/pt-BR/tools/overview.mdx @@ -0,0 +1,120 @@ +--- +title: "Visão Geral das Ferramentas" +description: "Descubra a vasta biblioteca do CrewAI com mais de 40 ferramentas para potencializar seus agentes de IA" +icon: "toolbox" +--- + +O CrewAI oferece uma biblioteca extensa de ferramentas pré-construídas para aprimorar as capacidades dos seus agentes. De processamento de arquivos a web scraping, consultas em bancos de dados a serviços de IA — temos tudo o que você precisa. + +## **Categorias de Ferramentas** + + + + Leia, escreva e pesquise em diversos formatos de arquivo, incluindo PDF, DOCX, JSON, CSV e muito mais. Perfeito para fluxos de processamento de documentos. + + + + Extraia dados de sites, automatize interações com navegadores e faça scraping de conteúdo em escala com ferramentas como Firecrawl, Selenium e outras. + + + + Realize buscas na web, encontre repositórios de código, pesquise conteúdo no YouTube e descubra informações em toda a internet. + + + + Conecte-se a bancos de dados SQL, repositórios vetoriais e data warehouses. Consulte MySQL, PostgreSQL, Snowflake, Qdrant e Weaviate. + + + + Gere imagens com DALL-E, execute tarefas de visão computacional, integre com LangChain, construa sistemas RAG e aproveite interpretadores de código. + + + + Interaja com serviços em nuvem incluindo AWS S3, Amazon Bedrock e outros serviços de armazenamento e IA na nuvem. + + + + Automatize fluxos de trabalho com Apify, Composio e outras plataformas de integração para conectar seus agentes a serviços externos. + + + +## **Acesso Rápido** + +Precisa de uma ferramenta específica? Aqui estão algumas opções populares: + + + + Implemente Geração com Recuperação de Dados (RAG) + + + API de busca do Google + + + Leia qualquer tipo de arquivo + + + Extraia conteúdo da web + + + Execute código Python + + + Acesse arquivos no AWS S3 + + + +## **Primeiros Passos** + +Para usar qualquer ferramenta em seu projeto CrewAI: + +1. **Importe** a ferramenta na configuração da sua crew +2. **Adicione** à lista de ferramentas do seu agente +3. **Configure** as chaves de API ou ajustes necessários + +```python +from crewai_tools import FileReadTool, SerperDevTool + +# Adicione as ferramentas ao seu agente +agent = Agent( + role="Research Analyst", + tools=[FileReadTool(), SerperDevTool()], + # ... outrAs configurações +) +``` + +Pronto para explorar? Escolha uma categoria acima para descobrir as ferramentas que se encaixam no seu caso de uso! diff --git a/docs/pt-BR/tools/search-research/bravesearchtool.mdx b/docs/pt-BR/tools/search-research/bravesearchtool.mdx new file mode 100644 index 000000000..bc72518b4 --- /dev/null +++ b/docs/pt-BR/tools/search-research/bravesearchtool.mdx @@ -0,0 +1,96 @@ +--- +title: Brave Search +description: O `BraveSearchTool` foi projetado para pesquisar na internet usando a Brave Search API. +icon: searchengin +--- + +# `BraveSearchTool` + +## Descrição + +Esta ferramenta foi desenvolvida para realizar buscas na web utilizando a Brave Search API. Ela permite que você pesquise na internet com uma consulta especificada e recupere resultados relevantes. A ferramenta suporta a personalização do número de resultados e buscas específicas por país. + +## Instalação + +Para incorporar esta ferramenta ao seu projeto, siga as instruções de instalação abaixo: + +```shell +pip install 'crewai[tools]' +``` + +## Passos para Começar + +Para utilizar o `BraveSearchTool` de forma eficaz, siga estes passos: + +1. **Instalação do Pacote**: Confirme que o pacote `crewai[tools]` está instalado no seu ambiente Python. +2. **Obtenção da Chave de API**: Obtenha uma chave de API do Brave Search registrando-se em [Brave Search API](https://api.search.brave.com/app/keys). +3. **Configuração do Ambiente**: Armazene a chave de API obtida em uma variável de ambiente chamada `BRAVE_API_KEY` para facilitar seu uso pela ferramenta. + +## Exemplo + +O exemplo a seguir demonstra como inicializar a ferramenta e executar uma busca com uma determinada consulta: + +```python Code +from crewai_tools import BraveSearchTool + +# Inicialize a ferramenta para capacidades de busca na internet +tool = BraveSearchTool() + +# Execute uma busca +results = tool.run(search_query="CrewAI agent framework") +print(results) +``` + +## Parâmetros + +O `BraveSearchTool` aceita os seguintes parâmetros: + +- **search_query**: Obrigatório. A consulta de pesquisa que você deseja usar para pesquisar na internet. +- **country**: Opcional. Especifique o país dos resultados da pesquisa. O padrão é string vazia. +- **n_results**: Opcional. Número de resultados de pesquisa a serem retornados. O padrão é `10`. +- **save_file**: Opcional. Se os resultados da pesquisa devem ser salvos em um arquivo. O padrão é `False`. + +## Exemplo com Parâmetros + +Veja um exemplo demonstrando como usar a ferramenta com parâmetros adicionais: + +```python Code +from crewai_tools import BraveSearchTool + +# Inicialize a ferramenta com parâmetros personalizados +tool = BraveSearchTool( + country="US", + n_results=5, + save_file=True +) + +# Execute uma busca +results = tool.run(search_query="Latest AI developments") +print(results) +``` + +## Exemplo de Integração com Agente + +Veja como integrar o `BraveSearchTool` com um agente CrewAI: + +```python Code +from crewai import Agent +from crewai.project import agent +from crewai_tools import BraveSearchTool + +# Inicialize a ferramenta +brave_search_tool = BraveSearchTool() + +# Defina um agente com o BraveSearchTool +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config["researcher"], + allow_delegation=False, + tools=[brave_search_tool] + ) +``` + +## Conclusão + +Ao integrar o `BraveSearchTool` em projetos Python, os usuários ganham a capacidade de realizar buscas em tempo real e relevantes na internet diretamente de suas aplicações. A ferramenta oferece uma interface simples para a poderosa Brave Search API, facilitando a recuperação e o processamento programático dos resultados de pesquisa. Seguindo as orientações de configuração e uso fornecidas, a incorporação desta ferramenta em projetos é simplificada e direta. \ No newline at end of file diff --git a/docs/pt-BR/tools/search-research/codedocssearchtool.mdx b/docs/pt-BR/tools/search-research/codedocssearchtool.mdx new file mode 100644 index 000000000..d10a4bd28 --- /dev/null +++ b/docs/pt-BR/tools/search-research/codedocssearchtool.mdx @@ -0,0 +1,84 @@ +--- +title: Pesquisa com RAG em Documentação de Código +description: O `CodeDocsSearchTool` é uma poderosa ferramenta RAG (Geração Aumentada por Recuperação) projetada para buscas semânticas em documentação de código. +icon: code +--- + +# `CodeDocsSearchTool` + + + **Experimental**: Ainda estamos trabalhando para melhorar as ferramentas, então pode haver comportamentos inesperados ou mudanças no futuro. + + +## Descrição + +O CodeDocsSearchTool é uma poderosa ferramenta RAG (Geração Aumentada por Recuperação) projetada para buscas semânticas em documentação de código. +Ela permite que usuários encontrem de forma eficiente informações ou tópicos específicos dentro da documentação de código. Ao fornecer um `docs_url` durante a inicialização, +a ferramenta restringe a busca àquele site de documentação em particular. Alternativamente, sem um `docs_url` específico, +ela realiza buscas em uma ampla variedade de documentações de código conhecidas ou descobertas durante sua execução, tornando-a versátil para diversas necessidades de busca em documentação. + +## Instalação + +Para começar a usar o CodeDocsSearchTool, primeiro instale o pacote crewai_tools via pip: + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo + +Utilize o CodeDocsSearchTool conforme abaixo para realizar buscas em documentação de código: + +```python Code +from crewai_tools import CodeDocsSearchTool + +# Para buscar qualquer conteúdo de documentação de código +# se a URL for conhecida ou descoberta durante a execução: +tool = CodeDocsSearchTool() + +# OU + +# Para focar sua busca especificamente em um site de documentação +# fornecendo sua URL: +tool = CodeDocsSearchTool(docs_url='https://docs.example.com/reference') +``` + + Substitua 'https://docs.example.com/reference' pela URL da documentação desejada + e 'How to use search tool' pela consulta de busca relevante às suas necessidades. + + +## Argumentos + +Os seguintes parâmetros podem ser usados para personalizar o comportamento do `CodeDocsSearchTool`: + +| Argumento | Tipo | Descrição | +|:----------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------| +| **docs_url** | `string` | _Opcional_. Especifica a URL da documentação de código a ser pesquisada. | + +## Modelo e embeddings personalizados + +Por padrão, a ferramenta utiliza a OpenAI tanto para embeddings quanto para sumarização. Para customizar o modelo, você pode usar um dicionário de configuração conforme abaixo: + +```python Code +tool = CodeDocsSearchTool( + config=dict( + llm=dict( + provider="ollama", # ou google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", # ou openai, ollama, ... + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/search-research/exasearchtool.mdx b/docs/pt-BR/tools/search-research/exasearchtool.mdx new file mode 100644 index 000000000..1bfb4e7d3 --- /dev/null +++ b/docs/pt-BR/tools/search-research/exasearchtool.mdx @@ -0,0 +1,52 @@ +--- +title: Carregador Web EXA Search +description: O `EXASearchTool` foi projetado para realizar uma busca semântica para uma consulta especificada a partir do conteúdo de um texto em toda a internet. +icon: globe-pointer +--- + +# `EXASearchTool` + +## Descrição + +O EXASearchTool foi projetado para realizar uma busca semântica para uma consulta especificada a partir do conteúdo de um texto em toda a internet. +Ele utiliza a API da [exa.ai](https://exa.ai/) para buscar e exibir os resultados de pesquisa mais relevantes com base na consulta fornecida pelo usuário. + +## Instalação + +Para incorporar esta ferramenta em seu projeto, siga as instruções de instalação abaixo: + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo + +O exemplo a seguir demonstra como inicializar a ferramenta e executar uma busca com uma consulta determinada: + +```python Code +from crewai_tools import EXASearchTool + +# Initialize the tool for internet searching capabilities +tool = EXASearchTool() +``` + +## Etapas para Começar + +Para usar o EXASearchTool de forma eficaz, siga estas etapas: + + + + Confirme se o pacote `crewai[tools]` está instalado em seu ambiente Python. + + + Adquira uma chave de API da [exa.ai](https://exa.ai/) registrando-se gratuitamente em [exa.ai](https://exa.ai/). + + + Armazene a chave de API obtida em uma variável de ambiente chamada `EXA_API_KEY` para facilitar o uso pela ferramenta. + + + +## Conclusão + +Ao integrar o `EXASearchTool` em projetos Python, os usuários ganham a capacidade de realizar buscas relevantes e em tempo real pela internet diretamente de suas aplicações. +Seguindo as orientações de configuração e uso fornecidas, a incorporação desta ferramenta em projetos torna-se simples e direta. \ No newline at end of file diff --git a/docs/pt-BR/tools/search-research/githubsearchtool.mdx b/docs/pt-BR/tools/search-research/githubsearchtool.mdx new file mode 100644 index 000000000..a5758db33 --- /dev/null +++ b/docs/pt-BR/tools/search-research/githubsearchtool.mdx @@ -0,0 +1,84 @@ +--- +title: Github Search +description: O `GithubSearchTool` foi desenvolvido para pesquisar sites e convertê-los em markdown limpo ou dados estruturados. +icon: github +--- + +# `GithubSearchTool` + + + Ainda estamos trabalhando para melhorar as ferramentas, portanto pode haver comportamentos inesperados ou mudanças no futuro. + + +## Descrição + +O GithubSearchTool é uma ferramenta de Recuperação Aprimorada por Geração (RAG) especificamente projetada para realizar buscas semânticas em repositórios GitHub. Utilizando funcionalidades avançadas de busca semântica, ele examina códigos, pull requests, issues e repositórios, tornando-se uma ferramenta essencial para desenvolvedores, pesquisadores ou qualquer pessoa que precise de informações precisas do GitHub. + +## Instalação + +Para usar o GithubSearchTool, primeiro certifique-se de que o pacote crewai_tools está instalado em seu ambiente Python: + +```shell +pip install 'crewai[tools]' +``` + +Esse comando instala o pacote necessário para rodar o GithubSearchTool juntamente com outras ferramentas incluídas no pacote crewai_tools. + +## Exemplo + +Veja como você pode usar o GithubSearchTool para realizar buscas semânticas dentro de um repositório GitHub: + +```python Code +from crewai_tools import GithubSearchTool + +# Inicialize a ferramenta para buscas semânticas em um repositório GitHub específico +tool = GithubSearchTool( + github_repo='https://github.com/example/repo', + gh_token='your_github_personal_access_token', + content_types=['code', 'issue'] # Opções: code, repo, pr, issue +) + +# OU + +# Inicialize a ferramenta para buscas semânticas em um repositório GitHub específico, permitindo que o agente pesquise em qualquer repositório caso tome conhecimento durante a execução +tool = GithubSearchTool( + gh_token='your_github_personal_access_token', + content_types=['code', 'issue'] # Opções: code, repo, pr, issue +) +``` + +## Argumentos + +- `github_repo` : A URL do repositório GitHub onde a busca será realizada. Este é um campo obrigatório e especifica o repositório alvo para sua pesquisa. +- `gh_token` : Seu Personal Access Token (PAT) do GitHub necessário para autenticação. Você pode criar um nas configurações da sua conta GitHub em Developer Settings > Personal Access Tokens. +- `content_types` : Especifica os tipos de conteúdo a serem incluídos na busca. É necessário fornecer uma lista dos tipos de conteúdo das seguintes opções: `code` para pesquisar dentro do código, +`repo` para pesquisar nas informações gerais do repositório, `pr` para pesquisar em pull requests, e `issue` para pesquisar nas issues. +Este campo é obrigatório e permite adaptar a busca para tipos específicos de conteúdo dentro do repositório GitHub. + +## Modelo e embeddings personalizados + +Por padrão, a ferramenta utiliza o OpenAI tanto para embeddings quanto para sumarização. Para personalizar o modelo, você pode usar um dicionário de configuração como no exemplo: + +```python Code +tool = GithubSearchTool( + config=dict( + llm=dict( + provider="ollama", # ou google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", # ou openai, ollama, ... + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/search-research/linkupsearchtool.mdx b/docs/pt-BR/tools/search-research/linkupsearchtool.mdx new file mode 100644 index 000000000..522b85a26 --- /dev/null +++ b/docs/pt-BR/tools/search-research/linkupsearchtool.mdx @@ -0,0 +1,112 @@ +--- +title: Linkup Search Tool +description: O `LinkupSearchTool` permite consultar a API do Linkup para obter informações contextuais. +icon: link +--- + +# `LinkupSearchTool` + +## Descrição + +O `LinkupSearchTool` fornece a capacidade de consultar a API do Linkup para obter informações contextuais e recuperar resultados estruturados. Esta ferramenta é ideal para enriquecer fluxos de trabalho com informações atualizadas e confiáveis do Linkup, permitindo que agentes acessem dados relevantes durante a execução de suas tarefas. + +## Instalação + +Para utilizar esta ferramenta, é necessário instalar o Linkup SDK: + +```shell +uv add linkup-sdk +``` + +## Passos para começar + +Para usar efetivamente o `LinkupSearchTool`, siga estes passos: + +1. **Chave de API**: Obtenha uma chave de API do Linkup. +2. **Configuração do Ambiente**: Configure seu ambiente com a chave de API. +3. **Instalar SDK**: Instale o Linkup SDK usando o comando acima. + +## Exemplo + +O exemplo a seguir demonstra como inicializar a ferramenta e usá-la em um agente: + +```python Code +from crewai_tools import LinkupSearchTool +from crewai import Agent +import os + +# Initialize the tool with your API key +linkup_tool = LinkupSearchTool(api_key=os.getenv("LINKUP_API_KEY")) + +# Define an agent that uses the tool +@agent +def researcher(self) -> Agent: + ''' + This agent uses the LinkupSearchTool to retrieve contextual information + from the Linkup API. + ''' + return Agent( + config=self.agents_config["researcher"], + tools=[linkup_tool] + ) +``` + +## Parâmetros + +O `LinkupSearchTool` aceita os seguintes parâmetros: + +### Parâmetros do Construtor +- **api_key**: Obrigatório. Sua chave de API do Linkup. + +### Parâmetros de Execução +- **query**: Obrigatório. O termo ou frase de busca. +- **depth**: Opcional. A profundidade da busca. O padrão é "standard". +- **output_type**: Opcional. O tipo de saída. O padrão é "searchResults". + +## Uso Avançado + +Você pode personalizar os parâmetros de busca para resultados mais específicos: + +```python Code +# Perform a search with custom parameters +results = linkup_tool.run( + query="Women Nobel Prize Physics", + depth="deep", + output_type="searchResults" +) +``` + +## Formato de Retorno + +A ferramenta retorna resultados no seguinte formato: + +```json +{ + "success": true, + "results": [ + { + "name": "Result Title", + "url": "https://example.com/result", + "content": "Content of the result..." + }, + // Additional results... + ] +} +``` + +Se ocorrer um erro, a resposta será: + +```json +{ + "success": false, + "error": "Error message" +} +``` + +## Tratamento de Erros + +A ferramenta lida com erros de API de forma amigável e fornece feedback estruturado. Se a requisição à API falhar, a ferramenta retornará um dicionário com `success: false` e uma mensagem de erro. + +## Conclusão + +O `LinkupSearchTool` oferece uma forma integrada de incorporar as capacidades de busca de informações contextuais do Linkup aos seus agentes CrewAI. Ao utilizar esta ferramenta, os agentes podem acessar informações relevantes e atualizadas para aprimorar sua tomada de decisão e execução de tarefas. \ No newline at end of file diff --git a/docs/pt-BR/tools/search-research/overview.mdx b/docs/pt-BR/tools/search-research/overview.mdx new file mode 100644 index 000000000..1883f2240 --- /dev/null +++ b/docs/pt-BR/tools/search-research/overview.mdx @@ -0,0 +1,71 @@ +--- +title: "Visão Geral" +description: "Realize pesquisas na web, encontre repositórios e pesquise informações em toda a internet" +icon: "face-smile" +--- + +Essas ferramentas permitem que seus agentes pesquisem na web, explorem tópicos e encontrem informações em diversas plataformas, incluindo motores de busca, GitHub e YouTube. + +## **Ferramentas Disponíveis** + + + + Integração com a API de busca do Google para capacidades abrangentes de pesquisa na web. + + + + Pesquisa voltada para privacidade com o índice independente de busca do Brave. + + + + Pesquisa impulsionada por IA para encontrar conteúdo específico e relevante. + + + + Pesquisa em tempo real na web com indexação de conteúdo atualizado. + + + + Pesquise repositórios do GitHub, códigos, issues e documentação. + + + + Pesquisa dentro de sites e domínios específicos. + + + + Pesquise em documentação de código e recursos técnicos. + + + + Pesquise canais do YouTube para encontrar conteúdos e criadores específicos. + + + + Encontre e analise vídeos do YouTube por assunto, palavra-chave ou critério. + + + +## **Casos de Uso Comuns** + +- **Pesquisa de Mercado**: Pesquise tendências de mercado e análise de concorrentes +- **Descoberta de Conteúdo**: Encontre artigos, vídeos e recursos relevantes +- **Pesquisa de Código**: Pesquise repositórios e documentação em busca de soluções +- **Geração de Leads**: Pesquise empresas e pessoas +- **Pesquisa Acadêmica**: Encontre artigos científicos e trabalhos técnicos + +```python +from crewai_tools import SerperDevTool, GitHubSearchTool, YoutubeVideoSearchTool + +# Create research tools +web_search = SerperDevTool() +code_search = GitHubSearchTool() +video_research = YoutubeVideoSearchTool() + +# Add to your agent +agent = Agent( + role="Research Analyst", + tools=[web_search, code_search, video_research], + goal="Gather comprehensive information on any topic" +) +``` diff --git a/docs/pt-BR/tools/search-research/serperdevtool.mdx b/docs/pt-BR/tools/search-research/serperdevtool.mdx new file mode 100644 index 000000000..9ef365679 --- /dev/null +++ b/docs/pt-BR/tools/search-research/serperdevtool.mdx @@ -0,0 +1,112 @@ +--- +title: Pesquisa Serper Google +description: O `SerperDevTool` é projetado para pesquisar na internet e retornar os resultados mais relevantes. +icon: google +--- + +# `SerperDevTool` + + + Ainda estamos trabalhando na melhoria das ferramentas, portanto, pode haver comportamentos inesperados ou mudanças no futuro. + + +## Descrição + +Esta ferramenta foi projetada para realizar buscas semânticas para uma consulta especificada a partir do conteúdo de um texto na internet. Ela utiliza a API do [serper.dev](https://serper.dev) +para buscar e exibir os resultados de pesquisa mais relevantes com base na consulta fornecida pelo usuário. + +## Instalação + +Para incorporar esta ferramenta em seu projeto, siga as instruções de instalação abaixo: + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo + +O exemplo a seguir demonstra como inicializar a ferramenta e executar uma busca com uma consulta fornecida: + +```python Code +from crewai_tools import SerperDevTool + +# Inicializar a ferramenta para capacidades de busca na internet +tool = SerperDevTool() +``` + +## Etapas para Começar + +Para utilizar o `SerperDevTool` de forma eficaz, siga estes passos: + +1. **Instalação do Pacote**: Confirme se o pacote `crewai[tools]` está instalado em seu ambiente Python. +2. **Obtenção da Chave de API**: Adquira uma chave de API do `serper.dev` registrando-se para uma conta gratuita em `serper.dev`. +3. **Configuração do Ambiente**: Armazene sua chave de API obtida em uma variável de ambiente chamada `SERPER_API_KEY` para facilitar o uso pela ferramenta. + +## Parâmetros + +O `SerperDevTool` possui vários parâmetros que serão passados para a API: + +- **search_url**: O endpoint da URL para a API de busca. (Padrão é `https://google.serper.dev/search`) + +- **country**: Opcional. Especifica o país para os resultados de busca. +- **location**: Opcional. Especifica a localização para os resultados de busca. +- **locale**: Opcional. Especifica o local para os resultados de busca. +- **n_results**: Número de resultados de busca a serem retornados. O padrão é `10`. + +Os valores para `country`, `location`, `locale` e `search_url` podem ser encontrados no [Serper Playground](https://serper.dev/playground). + +## Exemplo com Parâmetros + +Aqui está um exemplo demonstrando como usar a ferramenta com parâmetros adicionais: + +```python Code +from crewai_tools import SerperDevTool + +tool = SerperDevTool( + search_url="https://google.serper.dev/scholar", + n_results=2, +) + +print(tool.run(search_query="ChatGPT")) + +# Using Tool: Search the internet + +# Search results: Title: Role of chat gpt in public health +# Link: https://link.springer.com/article/10.1007/s10439-023-03172-7 +# Snippet: … ChatGPT in public health. In this overview, we will examine the potential uses of ChatGPT in +# --- +# Title: Potential use of chat gpt in global warming +# Link: https://link.springer.com/article/10.1007/s10439-023-03171-8 +# Snippet: … as ChatGPT, have the potential to play a critical role in advancing our understanding of climate +# --- + +``` + +```python Code +from crewai_tools import SerperDevTool + +tool = SerperDevTool( + country="fr", + locale="fr", + location="Paris, Paris, Ile-de-France, France", + n_results=2, +) + +print(tool.run(search_query="Jeux Olympiques")) + +# Using Tool: Search the internet + +# Search results: Title: Jeux Olympiques de Paris 2024 - Actualités, calendriers, résultats +# Link: https://olympics.com/fr/paris-2024 +# Snippet: Quels sont les sports présents aux Jeux Olympiques de Paris 2024 ? · Athlétisme · Aviron · Badminton · Basketball · Basketball 3x3 · Boxe · Breaking · Canoë ... +# --- +# Title: Billetterie Officielle de Paris 2024 - Jeux Olympiques et Paralympiques +# Link: https://tickets.paris2024.org/ +# Snippet: Achetez vos billets exclusivement sur le site officiel de la billetterie de Paris 2024 pour participer au plus grand événement sportif au monde. +# --- +``` + +## Conclusão + +Ao integrar o `SerperDevTool` em projetos Python, os usuários obtêm a capacidade de realizar buscas em tempo real e relevantes na internet diretamente de suas aplicações. +Os parâmetros atualizados permitem resultados de busca mais personalizados e localizados. Seguindo as diretrizes de configuração e uso fornecidas, a incorporação desta ferramenta nos projetos é simplificada e direta. \ No newline at end of file diff --git a/docs/pt-BR/tools/search-research/websitesearchtool.mdx b/docs/pt-BR/tools/search-research/websitesearchtool.mdx new file mode 100644 index 000000000..a80217f94 --- /dev/null +++ b/docs/pt-BR/tools/search-research/websitesearchtool.mdx @@ -0,0 +1,77 @@ +--- +title: Pesquisa RAG em Sites +description: O `WebsiteSearchTool` foi projetado para realizar uma busca RAG (Geração Aumentada por Recuperação) dentro do conteúdo de um site. +icon: globe-stand +--- + +# `WebsiteSearchTool` + + + O WebsiteSearchTool está atualmente em fase experimental. Estamos trabalhando ativamente para incorporar esta ferramenta em nosso conjunto de ofertas e atualizaremos a documentação conforme necessário. + + +## Descrição + +O WebsiteSearchTool foi concebido como um conceito para realizar buscas semânticas dentro do conteúdo de sites. +Ele visa aproveitar modelos avançados de aprendizado de máquina, como a Geração Aumentada por Recuperação (RAG), para navegar e extrair informações de URLs especificadas de forma eficiente. +Esta ferramenta pretende oferecer flexibilidade, permitindo que usuários realizem buscas em qualquer site ou foquem em sites específicos de seu interesse. +Por favor, note que os detalhes da implementação atual do WebsiteSearchTool estão em desenvolvimento, e as funcionalidades aqui descritas podem ainda não estar acessíveis. + +## Instalação + +Para preparar seu ambiente para quando o WebsiteSearchTool estiver disponível, você pode instalar o pacote fundamental com: + +```shell +pip install 'crewai[tools]' +``` + +Este comando instala as dependências necessárias para garantir que, assim que a ferramenta estiver totalmente integrada, os usuários possam começar a usá-la imediatamente. + +## Exemplo de Uso + +Abaixo estão exemplos de como o WebsiteSearchTool poderá ser utilizado em diferentes cenários. Por favor, observe que esses exemplos são ilustrativos e representam funcionalidades planejadas: + +```python Code +from crewai_tools import WebsiteSearchTool + +# Exemplo de inicialização da ferramenta que agentes podem usar +# para pesquisar em quaisquer sites descobertos +tool = WebsiteSearchTool() + +# Exemplo de limitação da busca ao conteúdo de um site específico, +# assim os agentes podem buscar somente dentro desse site +tool = WebsiteSearchTool(website='https://example.com') +``` + +## Argumentos + +- `website`: Um argumento opcional destinado a especificar a URL do site para buscas direcionadas. Este argumento foi projetado para aumentar a flexibilidade da ferramenta, permitindo buscas mais focadas quando necessário. + +## Opções de Personalização + +Por padrão, a ferramenta utiliza a OpenAI tanto para embeddings quanto para sumarização. Para personalizar o modelo, você pode usar um dicionário de configuração, conforme o exemplo abaixo: + + +```python Code +tool = WebsiteSearchTool( + config=dict( + llm=dict( + provider="ollama", # ou google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", # ou openai, ollama, ... + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/search-research/youtubechannelsearchtool.mdx b/docs/pt-BR/tools/search-research/youtubechannelsearchtool.mdx new file mode 100644 index 000000000..a0750da5a --- /dev/null +++ b/docs/pt-BR/tools/search-research/youtubechannelsearchtool.mdx @@ -0,0 +1,194 @@ +--- +title: Busca RAG em Canal do YouTube +description: O `YoutubeChannelSearchTool` foi desenvolvido para realizar buscas RAG (Retrieval-Augmented Generation) no conteúdo de um canal do Youtube. +icon: youtube +--- + +# `YoutubeChannelSearchTool` + + + Ainda estamos trabalhando para melhorar as ferramentas, então pode haver comportamentos inesperados ou alterações no futuro. + + +## Descrição + +Esta ferramenta foi desenvolvida para realizar buscas semânticas dentro do conteúdo de um canal específico do Youtube. +Aproveitando a metodologia RAG (Retrieval-Augmented Generation), ela fornece resultados de busca relevantes, +tornando-se indispensável para extrair informações ou encontrar conteúdos específicos sem a necessidade de percorrer manualmente os vídeos. +Ela otimiza o processo de busca em canais do Youtube, sendo ideal para pesquisadores, criadores de conteúdo e espectadores que buscam informações ou temas específicos. + +## Instalação + +Para utilizar o YoutubeChannelSearchTool, é necessário instalar o pacote `crewai_tools`. Execute o seguinte comando no seu terminal para instalar: + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo + +O exemplo a seguir demonstra como utilizar o `YoutubeChannelSearchTool` com um agente CrewAI: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import YoutubeChannelSearchTool + +# Inicializa a ferramenta para buscas gerais em canais do YouTube +youtube_channel_tool = YoutubeChannelSearchTool() + +# Define um agente que utiliza a ferramenta +channel_researcher = Agent( + role="Channel Researcher", + goal="Extrair informações relevantes de canais do YouTube", + backstory="Um pesquisador especialista em analisar conteúdos de canais do YouTube.", + tools=[youtube_channel_tool], + verbose=True, +) + +# Exemplo de tarefa para buscar informações em um canal específico +research_task = Task( + description="Buscar informações sobre tutoriais de machine learning no canal do YouTube {youtube_channel_handle}", + expected_output="Um resumo dos principais tutoriais de machine learning disponíveis no canal.", + agent=channel_researcher, +) + +# Cria e executa o crew +crew = Crew(agents=[channel_researcher], tasks=[research_task]) +result = crew.kickoff(inputs={"youtube_channel_handle": "@exampleChannel"}) +``` + +Você também pode inicializar a ferramenta com um handle específico de canal do YouTube: + +```python Code +# Inicializa a ferramenta com o handle específico de um canal do YouTube +youtube_channel_tool = YoutubeChannelSearchTool( + youtube_channel_handle='@exampleChannel' +) + +# Define um agente que utiliza a ferramenta +channel_researcher = Agent( + role="Channel Researcher", + goal="Extrair informações relevantes de um canal específico do YouTube", + backstory="Um pesquisador especialista em analisar conteúdos de canais do YouTube.", + tools=[youtube_channel_tool], + verbose=True, +) +``` + +## Parâmetros + +O `YoutubeChannelSearchTool` aceita os seguintes parâmetros: + +- **youtube_channel_handle**: Opcional. O handle do canal do YouTube para realizar a busca. Se fornecido durante a inicialização, o agente não precisará informá-lo ao utilizar a ferramenta. Se o handle não começar com '@', será adicionado automaticamente. +- **config**: Opcional. Configurações para o sistema RAG subjacente, incluindo parâmetros de LLM e embedder. +- **summarize**: Opcional. Indica se o conteúdo recuperado deve ser resumido. O padrão é `False`. + +Ao utilizar a ferramenta com um agente, o agente deverá fornecer: + +- **search_query**: Obrigatório. A consulta de busca para encontrar informações relevantes no conteúdo do canal. +- **youtube_channel_handle**: Obrigatório apenas se não for fornecido durante a inicialização. O handle do canal do YouTube onde realizar a busca. + +## Modelo Personalizado e Embeddings + +Por padrão, a ferramenta utiliza o OpenAI tanto para embeddings quanto para sumarização. Para personalizar o modelo, é possível usar um dicionário de configuração como no exemplo: + +```python Code +youtube_channel_tool = YoutubeChannelSearchTool( + config=dict( + llm=dict( + provider="ollama", # ou google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", # ou openai, ollama, ... + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` + +## Exemplo de Integração com Agente + +Veja um exemplo mais detalhado de como integrar o `YoutubeChannelSearchTool` com um agente CrewAI: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import YoutubeChannelSearchTool + +# Inicializa a ferramenta +youtube_channel_tool = YoutubeChannelSearchTool() + +# Define um agente que utiliza a ferramenta +channel_researcher = Agent( + role="Channel Researcher", + goal="Extrair e analisar informações de canais do YouTube", + backstory="""Você é um pesquisador especialista em canais, com experiência + em extrair e analisar informações de canais do YouTube. Você possui olho clínico para detalhes + e pode rapidamente identificar pontos-chave e insights a partir do conteúdo em vídeo de todo o canal.""", + tools=[youtube_channel_tool], + verbose=True, +) + +# Crie uma tarefa para o agente +research_task = Task( + description=""" + Buscar informações sobre projetos e tutoriais de ciência de dados + no canal do YouTube {youtube_channel_handle}. + + Foque em: + 1. Principais técnicas de ciência de dados abordadas + 2. Séries de tutoriais populares + 3. Vídeos mais vistos ou recomendados + + Forneça um resumo abrangente sobre esses pontos. + """, + expected_output="Um resumo detalhado sobre o conteúdo de ciência de dados disponível no canal.", + agent=channel_researcher, +) + +# Execute a tarefa +crew = Crew(agents=[channel_researcher], tasks=[research_task]) +result = crew.kickoff(inputs={"youtube_channel_handle": "@exampleDataScienceChannel"}) +``` + +## Detalhes da Implementação + +O `YoutubeChannelSearchTool` é implementado como uma subclasse de `RagTool`, que fornece a funcionalidade base para Retrieval-Augmented Generation: + +```python Code +class YoutubeChannelSearchTool(RagTool): + name: str = "Search a Youtube Channels content" + description: str = "A tool that can be used to semantic search a query from a Youtube Channels content." + args_schema: Type[BaseModel] = YoutubeChannelSearchToolSchema + + def __init__(self, youtube_channel_handle: Optional[str] = None, **kwargs): + super().__init__(**kwargs) + if youtube_channel_handle is not None: + kwargs["data_type"] = DataType.YOUTUBE_CHANNEL + self.add(youtube_channel_handle) + self.description = f"A tool that can be used to semantic search a query the {youtube_channel_handle} Youtube Channels content." + self.args_schema = FixedYoutubeChannelSearchToolSchema + self._generate_description() + + def add( + self, + youtube_channel_handle: str, + **kwargs: Any, + ) -> None: + if not youtube_channel_handle.startswith("@"): + youtube_channel_handle = f"@{youtube_channel_handle}" + super().add(youtube_channel_handle, **kwargs) +``` + +## Conclusão + +O `YoutubeChannelSearchTool` oferece uma forma poderosa de buscar e extrair informações do conteúdo de canais do YouTube utilizando técnicas RAG. Ao possibilitar que agentes busquem entre todos os vídeos de um canal, facilita tarefas de extração e análise de informações que seriam difíceis de executar manualmente. Esta ferramenta é especialmente útil para pesquisa, análise de conteúdo e extração de conhecimento de canais do YouTube. \ No newline at end of file diff --git a/docs/pt-BR/tools/search-research/youtubevideosearchtool.mdx b/docs/pt-BR/tools/search-research/youtubevideosearchtool.mdx new file mode 100644 index 000000000..969d9a577 --- /dev/null +++ b/docs/pt-BR/tools/search-research/youtubevideosearchtool.mdx @@ -0,0 +1,187 @@ +--- +title: Pesquisa RAG em Vídeos do YouTube +description: O `YoutubeVideoSearchTool` foi projetado para realizar uma busca RAG (Geração Auxiliada por Recuperação) no conteúdo de um vídeo do Youtube. +icon: youtube +--- + +# `YoutubeVideoSearchTool` + + + Ainda estamos trabalhando para melhorar as ferramentas, portanto podem ocorrer comportamentos inesperados ou mudanças no futuro. + + +## Descrição + +Esta ferramenta faz parte do pacote `crewai_tools` e foi projetada para realizar buscas semânticas dentro do conteúdo de vídeos do Youtube, utilizando técnicas de Geração Auxiliada por Recuperação (RAG). +É uma das diversas ferramentas de "Pesquisa" do pacote que aproveitam RAG para diferentes fontes. +O YoutubeVideoSearchTool permite flexibilidade nas buscas: usuários podem pesquisar em qualquer conteúdo de vídeo do Youtube sem especificar uma URL, +ou podem direcionar sua busca para um vídeo específico fornecendo sua URL. + +## Instalação + +Para utilizar o `YoutubeVideoSearchTool`, é necessário primeiro instalar o pacote `crewai_tools`. +Esse pacote contém o `YoutubeVideoSearchTool` entre outras utilidades desenvolvidas para melhorar suas tarefas de análise e processamento de dados. +Instale o pacote executando o seguinte comando em seu terminal: + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo + +O exemplo a seguir demonstra como usar o `YoutubeVideoSearchTool` com um agente CrewAI: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import YoutubeVideoSearchTool + +# Inicialize a ferramenta para buscas gerais em vídeos do YouTube +youtube_search_tool = YoutubeVideoSearchTool() + +# Defina um agente que usa a ferramenta +video_researcher = Agent( + role="Video Researcher", + goal="Extract relevant information from YouTube videos", + backstory="An expert researcher who specializes in analyzing video content.", + tools=[youtube_search_tool], + verbose=True, +) + +# Exemplo de tarefa para buscar informações em um vídeo específico +research_task = Task( + description="Search for information about machine learning frameworks in the YouTube video at {youtube_video_url}", + expected_output="A summary of the key machine learning frameworks mentioned in the video.", + agent=video_researcher, +) + +# Crie e execute a crew +crew = Crew(agents=[video_researcher], tasks=[research_task]) +result = crew.kickoff(inputs={"youtube_video_url": "https://youtube.com/watch?v=example"}) +``` + +Você também pode inicializar a ferramenta com a URL de um vídeo específico do YouTube: + +```python Code +# Inicialize a ferramenta com a URL de um vídeo específico do YouTube +youtube_search_tool = YoutubeVideoSearchTool( + youtube_video_url='https://youtube.com/watch?v=example' +) + +# Defina um agente que usa a ferramenta +video_researcher = Agent( + role="Video Researcher", + goal="Extract relevant information from a specific YouTube video", + backstory="An expert researcher who specializes in analyzing video content.", + tools=[youtube_search_tool], + verbose=True, +) +``` + +## Parâmetros + +O `YoutubeVideoSearchTool` aceita os seguintes parâmetros: + +- **youtube_video_url**: Opcional. A URL do vídeo do YouTube para pesquisa. Se fornecida durante a inicialização, o agente não precisará especificar ao utilizar a ferramenta. +- **config**: Opcional. Configuração para o sistema RAG subjacente, incluindo definições de LLM e embedder. +- **summarize**: Opcional. Indica se o conteúdo recuperado deve ser resumido. O padrão é `False`. + +Ao usar a ferramenta com um agente, é necessário fornecer: + +- **search_query**: Obrigatório. A consulta de busca para encontrar informações relevantes no conteúdo do vídeo. +- **youtube_video_url**: Obrigatório somente se não for fornecida na inicialização. A URL do vídeo do YouTube a ser pesquisado. + +## Modelo e Embeddings Personalizados + +Por padrão, a ferramenta utiliza OpenAI tanto para embeddings quanto para sumarização. Para personalizar o modelo, utilize um dicionário de configuração conforme exemplo: + +```python Code +youtube_search_tool = YoutubeVideoSearchTool( + config=dict( + llm=dict( + provider="ollama", # ou google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google", # ou openai, ollama, ... + config=dict( + model="models/embedding-001", + task_type="retrieval_document", + # title="Embeddings", + ), + ), + ) +) +``` + +## Exemplo de Integração com Agente + +Aqui está um exemplo mais detalhado de como integrar o `YoutubeVideoSearchTool` com um agente CrewAI: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import YoutubeVideoSearchTool + +# Inicialize a ferramenta +youtube_search_tool = YoutubeVideoSearchTool() + +# Defina um agente que usa a ferramenta +video_researcher = Agent( + role="Video Researcher", + goal="Extract and analyze information from YouTube videos", + backstory="""You are an expert video researcher who specializes in extracting + and analyzing information from YouTube videos. You have a keen eye for detail + and can quickly identify key points and insights from video content.""", + tools=[youtube_search_tool], + verbose=True, +) + +# Crie uma tarefa para o agente +research_task = Task( + description=""" + Search for information about recent advancements in artificial intelligence + in the YouTube video at {youtube_video_url}. + + Focus on: + 1. Key AI technologies mentioned + 2. Real-world applications discussed + 3. Future predictions made by the speaker + + Provide a comprehensive summary of these points. + """, + expected_output="A detailed summary of AI advancements, applications, and future predictions from the video.", + agent=video_researcher, +) + +# Execute a tarefa +crew = Crew(agents=[video_researcher], tasks=[research_task]) +result = crew.kickoff(inputs={"youtube_video_url": "https://youtube.com/watch?v=example"}) +``` + +## Detalhes de Implementação + +O `YoutubeVideoSearchTool` é implementado como uma subclasse de `RagTool`, que fornece a funcionalidade base para Geração Auxiliada por Recuperação: + +```python Code +class YoutubeVideoSearchTool(RagTool): + name: str = "Search a Youtube Video content" + description: str = "A tool that can be used to semantic search a query from a Youtube Video content." + args_schema: Type[BaseModel] = YoutubeVideoSearchToolSchema + + def __init__(self, youtube_video_url: Optional[str] = None, **kwargs): + super().__init__(**kwargs) + if youtube_video_url is not None: + kwargs["data_type"] = DataType.YOUTUBE_VIDEO + self.add(youtube_video_url) + self.description = f"A tool that can be used to semantic search a query the {youtube_video_url} Youtube Video content." + self.args_schema = FixedYoutubeVideoSearchToolSchema + self._generate_description() +``` + +## Conclusão + +O `YoutubeVideoSearchTool` oferece uma maneira poderosa de pesquisar e extrair informações de conteúdos de vídeos do YouTube utilizando técnicas RAG. Ao possibilitar que agentes pesquisem dentro do conteúdo dos vídeos, facilita tarefas de extração e análise de informação que anteriormente seriam difíceis de realizar. Esta ferramenta é especialmente útil para pesquisas, análise de conteúdo e extração de conhecimento a partir de fontes em vídeo. \ No newline at end of file diff --git a/docs/pt-BR/tools/web-scraping/browserbaseloadtool.mdx b/docs/pt-BR/tools/web-scraping/browserbaseloadtool.mdx new file mode 100644 index 000000000..b2c71fd8a --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/browserbaseloadtool.mdx @@ -0,0 +1,50 @@ +--- +title: Carregador Web Browserbase +description: O Browserbase é uma plataforma para desenvolvedores para executar, gerenciar e monitorar navegadores headless de forma confiável. +icon: browser +--- + +# `BrowserbaseLoadTool` + +## Descrição + +[Browserbase](https://browserbase.com) é uma plataforma para desenvolvedores que permite executar, gerenciar e monitorar navegadores headless de forma confiável. + +Potencialize suas buscas de dados para IA com: + + - [Infraestrutura Serverless](https://docs.browserbase.com/under-the-hood) fornecendo navegadores confiáveis para extrair dados de interfaces complexas + - [Modo Stealth](https://docs.browserbase.com/features/stealth-mode) com táticas de fingerprinting e resolução automática de captcha incluídas + - [Depurador de Sessão](https://docs.browserbase.com/features/sessions) para inspecionar sua Sessão do Navegador com linha do tempo de rede e logs + - [Depuração Ao Vivo](https://docs.browserbase.com/guides/session-debug-connection/browser-remote-control) para depurar rapidamente sua automação + +## Instalação + +- Obtenha uma chave de API e o Project ID em [browserbase.com](https://browserbase.com) e defina-os nas variáveis de ambiente (`BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`). +- Instale o [SDK do Browserbase](http://github.com/browserbase/python-sdk) juntamente com o pacote `crewai[tools]`: + +```shell +pip install browserbase 'crewai[tools]' +``` + +## Exemplo + +Utilize o BrowserbaseLoadTool conforme abaixo para permitir que seu agente carregue sites: + +```python Code +from crewai_tools import BrowserbaseLoadTool + +# Inicialize a ferramenta com a chave da API do Browserbase e o Project ID +tool = BrowserbaseLoadTool() +``` + +## Argumentos + +Os parâmetros a seguir podem ser usados para customizar o comportamento do `BrowserbaseLoadTool`: + +| Argumento | Tipo | Descrição | +|:-----------------|:----------|:----------------------------------------------------------------------------------------------------------------------------------| +| **api_key** | `string` | _Opcional_. Chave de API do Browserbase. Padrão é a variável de ambiente `BROWSERBASE_API_KEY`. | +| **project_id** | `string` | _Opcional_. Project ID do Browserbase. Padrão é a variável de ambiente `BROWSERBASE_PROJECT_ID`. | +| **text_content** | `bool` | _Opcional_. Recuperar somente o conteúdo em texto. O padrão é `False`. | +| **session_id** | `string` | _Opcional_. Forneça um Session ID existente. | +| **proxy** | `bool` | _Opcional_. Habilitar/Desabilitar proxies. O padrão é `False`. | \ No newline at end of file diff --git a/docs/pt-BR/tools/web-scraping/firecrawlcrawlwebsitetool.mdx b/docs/pt-BR/tools/web-scraping/firecrawlcrawlwebsitetool.mdx new file mode 100644 index 000000000..2d2766296 --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/firecrawlcrawlwebsitetool.mdx @@ -0,0 +1,47 @@ +--- +title: Firecrawl Crawl Website +description: O `FirecrawlCrawlWebsiteTool` foi projetado para rastrear e converter sites em markdown limpo ou dados estruturados. +icon: fire-flame +--- + +# `FirecrawlCrawlWebsiteTool` + +## Descrição + +[Firecrawl](https://firecrawl.dev) é uma plataforma para rastrear e converter qualquer site em markdown limpo ou dados estruturados. + +## Instalação + +- Obtenha uma chave de API em [firecrawl.dev](https://firecrawl.dev) e defina-a nas variáveis de ambiente (`FIRECRAWL_API_KEY`). +- Instale o [SDK do Firecrawl](https://github.com/mendableai/firecrawl) junto com o pacote `crewai[tools]`: + +```shell +pip install firecrawl-py 'crewai[tools]' +``` + +## Exemplo + +Utilize o FirecrawlScrapeFromWebsiteTool como a seguir para permitir que seu agente carregue sites: + +```python Code +from crewai_tools import FirecrawlCrawlWebsiteTool + +tool = FirecrawlCrawlWebsiteTool(url='firecrawl.dev') +``` + +## Argumentos + +- `api_key`: Opcional. Especifica a chave de API do Firecrawl. Por padrão, utiliza a variável de ambiente `FIRECRAWL_API_KEY`. +- `url`: A URL base para iniciar o rastreamento. +- `page_options`: Opcional. + - `onlyMainContent`: Opcional. Retorna apenas o conteúdo principal da página, excluindo cabeçalhos, navegações, rodapés, etc. + - `includeHtml`: Opcional. Inclui o conteúdo HTML bruto da página. Vai adicionar uma chave html na resposta. +- `crawler_options`: Opcional. Opções para controlar o comportamento do rastreamento. + - `includes`: Opcional. Padrões de URL para incluir no rastreamento. + - `exclude`: Opcional. Padrões de URL para excluir do rastreamento. + - `generateImgAltText`: Opcional. Gera texto alternativo para imagens usando LLMs (requer um plano pago). + - `returnOnlyUrls`: Opcional. Se verdadeiro, retorna apenas as URLs como uma lista no status do rastreamento. Nota: a resposta será uma lista de URLs dentro do campo data, não uma lista de documentos. + - `maxDepth`: Opcional. Profundidade máxima de rastreamento. Profundidade 1 é a URL base, profundidade 2 inclui a URL base e seus filhos diretos, e assim por diante. + - `mode`: Opcional. O modo de rastreamento a ser utilizado. O modo rápido rastreia 4x mais rápido em sites sem sitemap, mas pode não ser tão preciso e não deve ser usado em sites fortemente renderizados com JavaScript. + - `limit`: Opcional. Número máximo de páginas a serem rastreadas. + - `timeout`: Opcional. Tempo limite em milissegundos para a operação de rastreamento. \ No newline at end of file diff --git a/docs/pt-BR/tools/web-scraping/firecrawlscrapewebsitetool.mdx b/docs/pt-BR/tools/web-scraping/firecrawlscrapewebsitetool.mdx new file mode 100644 index 000000000..8728651f3 --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/firecrawlscrapewebsitetool.mdx @@ -0,0 +1,43 @@ +--- +title: Firecrawl Scrape Website +description: A ferramenta `FirecrawlScrapeWebsiteTool` foi projetada para fazer scraping de sites e convertê-los em markdown limpo ou dados estruturados. +icon: fire-flame +--- + +# `FirecrawlScrapeWebsiteTool` + +## Descrição + +[Firecrawl](https://firecrawl.dev) é uma plataforma para rastrear e converter qualquer site em markdown limpo ou dados estruturados. + +## Instalação + +- Obtenha uma chave de API em [firecrawl.dev](https://firecrawl.dev) e defina-a nas variáveis de ambiente (`FIRECRAWL_API_KEY`). +- Instale o [Firecrawl SDK](https://github.com/mendableai/firecrawl) junto com o pacote `crewai[tools]`: + +```shell +pip install firecrawl-py 'crewai[tools]' +``` + +## Exemplo + +Utilize o FirecrawlScrapeWebsiteTool da seguinte forma para permitir que seu agente carregue sites: + +```python Code +from crewai_tools import FirecrawlScrapeWebsiteTool + +tool = FirecrawlScrapeWebsiteTool(url='firecrawl.dev') +``` + +## Argumentos + +- `api_key`: Opcional. Especifica a chave de API do Firecrawl. O padrão é a variável de ambiente `FIRECRAWL_API_KEY`. +- `url`: A URL a ser raspada. +- `page_options`: Opcional. + - `onlyMainContent`: Opcional. Retorna apenas o conteúdo principal da página, excluindo cabeçalhos, navegações, rodapés, etc. + - `includeHtml`: Opcional. Inclui o conteúdo HTML bruto da página. Irá gerar uma chave html na resposta. +- `extractor_options`: Opcional. Opções para extração baseada em LLM de informações estruturadas do conteúdo da página + - `mode`: O modo de extração a ser utilizado, atualmente suporta 'llm-extraction' + - `extractionPrompt`: Opcional. Um prompt descrevendo quais informações extrair da página + - `extractionSchema`: Opcional. O esquema para os dados a serem extraídos +- `timeout`: Opcional. Timeout em milissegundos para a requisição \ No newline at end of file diff --git a/docs/pt-BR/tools/web-scraping/firecrawlsearchtool.mdx b/docs/pt-BR/tools/web-scraping/firecrawlsearchtool.mdx new file mode 100644 index 000000000..91df03576 --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/firecrawlsearchtool.mdx @@ -0,0 +1,41 @@ +--- +title: Firecrawl Search +description: O `FirecrawlSearchTool` foi projetado para pesquisar sites e convertê-los em markdown limpo ou dados estruturados. +icon: fire-flame +--- + +# `FirecrawlSearchTool` + +## Descrição + +[Firecrawl](https://firecrawl.dev) é uma plataforma para rastrear e converter qualquer site em markdown limpo ou dados estruturados. + +## Instalação + +- Obtenha uma chave de API em [firecrawl.dev](https://firecrawl.dev) e defina-a nas variáveis de ambiente (`FIRECRAWL_API_KEY`). +- Instale o [Firecrawl SDK](https://github.com/mendableai/firecrawl) junto com o pacote `crewai[tools]`: + +```shell +pip install firecrawl-py 'crewai[tools]' +``` + +## Exemplo + +Utilize o FirecrawlSearchTool da seguinte forma para permitir que seu agente carregue sites: + +```python Code +from crewai_tools import FirecrawlSearchTool + +tool = FirecrawlSearchTool(query='what is firecrawl?') +``` + +## Argumentos + +- `api_key`: Opcional. Especifica a chave de API do Firecrawl. O padrão é a variável de ambiente `FIRECRAWL_API_KEY`. +- `query`: A string da consulta de busca a ser utilizada na pesquisa. +- `page_options`: Opcional. Opções para formatação dos resultados. + - `onlyMainContent`: Opcional. Retorna somente o conteúdo principal da página, excluindo cabeçalhos, navegações, rodapés, etc. + - `includeHtml`: Opcional. Inclui o conteúdo HTML bruto da página. Vai gerar uma chave html na resposta. + - `fetchPageContent`: Opcional. Busca o conteúdo completo da página. +- `search_options`: Opcional. Opções para controle do comportamento de rastreamento. + - `limit`: Opcional. Número máximo de páginas a rastrear. \ No newline at end of file diff --git a/docs/pt-BR/tools/web-scraping/hyperbrowserloadtool.mdx b/docs/pt-BR/tools/web-scraping/hyperbrowserloadtool.mdx new file mode 100644 index 000000000..abeacae7b --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/hyperbrowserloadtool.mdx @@ -0,0 +1,86 @@ +--- +title: Hyperbrowser Load Tool +description: O `HyperbrowserLoadTool` permite realizar web scraping e crawling utilizando o Hyperbrowser. +icon: globe +--- + +# `HyperbrowserLoadTool` + +## Descrição + +O `HyperbrowserLoadTool` permite realizar web scraping e crawling utilizando o [Hyperbrowser](https://hyperbrowser.ai), uma plataforma para executar e escalar browsers headless. Essa ferramenta possibilita extrair dados de uma única página ou rastrear um site inteiro, retornando o conteúdo em markdown ou HTML corretamente formatado. + +Principais Características: +- Escalabilidade Instantânea – Inicie centenas de sessões de browser em segundos sem se preocupar com infraestrutura +- Integração Simples – Funciona perfeitamente com ferramentas populares como Puppeteer e Playwright +- APIs Poderosas – APIs fáceis de usar para scraping/crawling de qualquer site +- Supera Medidas Anti-Bot – Inclui modo stealth, bloqueio de anúncios, resolução automática de CAPTCHA e proxies rotativos + +## Instalação + +Para utilizar esta ferramenta, você precisa instalar o SDK do Hyperbrowser: + +```shell +uv add hyperbrowser +``` + +## Passos para Começar + +Para usar efetivamente o `HyperbrowserLoadTool`, siga estes passos: + +1. **Cadastre-se**: Vá até o [Hyperbrowser](https://app.hyperbrowser.ai/) para criar uma conta e gerar uma chave de API. +2. **Chave de API**: Defina a variável de ambiente `HYPERBROWSER_API_KEY` ou passe-a diretamente no construtor da ferramenta. +3. **Instale o SDK**: Instale o SDK do Hyperbrowser usando o comando acima. + +## Exemplo + +O exemplo a seguir demonstra como inicializar a ferramenta e utilizá-la para extrair dados de um site: + +```python Code +from crewai_tools import HyperbrowserLoadTool +from crewai import Agent + +# Initialize the tool with your API key +tool = HyperbrowserLoadTool(api_key="your_api_key") # Or use environment variable + +# Define an agent that uses the tool +@agent +def web_researcher(self) -> Agent: + ''' + This agent uses the HyperbrowserLoadTool to scrape websites + and extract information. + ''' + return Agent( + config=self.agents_config["web_researcher"], + tools=[tool] + ) +``` + +## Parâmetros + +O `HyperbrowserLoadTool` aceita os seguintes parâmetros: + +### Parâmetros do Construtor +- **api_key**: Opcional. Sua chave de API do Hyperbrowser. Se não fornecida, será lida da variável de ambiente `HYPERBROWSER_API_KEY`. + +### Parâmetros de Execução +- **url**: Obrigatório. A URL do site a ser extraído ou rastreado. +- **operation**: Opcional. A operação a ser realizada no site. Pode ser 'scrape' ou 'crawl'. O padrão é 'scrape'. +- **params**: Opcional. Parâmetros adicionais para a operação de scraping ou crawling. + +## Parâmetros Suportados + +Para informações detalhadas sobre todos os parâmetros suportados, acesse: +- [Parâmetros de Scrape](https://docs.hyperbrowser.ai/reference/sdks/python/scrape#start-scrape-job-and-wait) +- [Parâmetros de Crawl](https://docs.hyperbrowser.ai/reference/sdks/python/crawl#start-crawl-job-and-wait) + +## Formato de Retorno + +A ferramenta retorna o conteúdo nos seguintes formatos: + +- Para operações **scrape**: O conteúdo da página no formato markdown ou HTML. +- Para operações **crawl**: O conteúdo de cada página separado por divisores, incluindo a URL de cada página. + +## Conclusão + +O `HyperbrowserLoadTool` oferece uma maneira poderosa de realizar scraping e crawling em sites, lidando com cenários complexos como medidas anti-bot, CAPTCHAs e muito mais. Aproveitando a plataforma do Hyperbrowser, essa ferramenta permite que agentes acessem e extraiam conteúdo da web de forma eficiente. \ No newline at end of file diff --git a/docs/pt-BR/tools/web-scraping/overview.mdx b/docs/pt-BR/tools/web-scraping/overview.mdx new file mode 100644 index 000000000..a1a1d879e --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/overview.mdx @@ -0,0 +1,107 @@ +--- +title: "Visão Geral" +description: "Extraia dados de websites e automatize interações com o navegador utilizando poderosas ferramentas de scraping" +icon: "face-smile" +--- + +Essas ferramentas permitem que seus agentes interajam com a web, extraiam dados de websites e automatizem tarefas baseadas em navegador. De raspagem simples a automação complexa de navegador, essas ferramentas cobrem todas as suas necessidades de interação com a web. + +## **Ferramentas Disponíveis** + + + + Ferramenta de raspagem de uso geral para extrair conteúdo de qualquer site. + + + + Extraia elementos específicos de páginas web com capacidades de raspagem precisa. + + + + Rastreie sites inteiros de forma sistemática com o poderoso mecanismo do Firecrawl. + + + + Raspagem web de alta performance com as capacidades avançadas do Firecrawl. + + + + Pesquise e extraia conteúdos específicos utilizando os recursos de busca do Firecrawl. + + + + Automação de navegador e scraping com as capacidades do Selenium WebDriver. + + + + Raspagem profissional de web com o serviço premium do ScrapFly. + + + + Raspagem baseada em grafos para relacionamentos de dados complexos. + + + + Rastreio abrangente de sites e capacidades de extração de dados. + + + + Automação de navegador baseada em nuvem com a infraestrutura do BrowserBase. + + + + Interações rápidas com o navegador através do engine otimizado do HyperBrowser. + + + + Automação inteligente de navegador com comandos em linguagem natural. + + + + Acesse dados web em escala com o Oxylabs. + + + +## **Casos de Uso Comuns** + +- **Extração de Dados**: Raspagem de informações de produtos, preços e avaliações +- **Monitoramento de Conteúdo**: Acompanhe mudanças em sites e fontes de notícias +- **Geração de Leads**: Extraia informações de contato e dados de empresas +- **Pesquisa de Mercado**: Coleta de inteligência competitiva e dados de mercado +- **Testes & QA**: Automatize fluxos de teste e validação em navegadores +- **Mídias Sociais**: Extraia posts, comentários e análises de redes sociais + +## **Exemplo de Início Rápido** + +```python +from crewai_tools import ScrapeWebsiteTool, FirecrawlScrapeWebsiteTool, SeleniumScrapingTool + +# Create scraping tools +simple_scraper = ScrapeWebsiteTool() +advanced_scraper = FirecrawlScrapeWebsiteTool() +browser_automation = SeleniumScrapingTool() + +# Add to your agent +agent = Agent( + role="Web Research Specialist", + tools=[simple_scraper, advanced_scraper, browser_automation], + goal="Extract and analyze web data efficiently" +) +``` + +## **Boas Práticas de Scraping** + +- **Respeite o robots.txt**: Sempre verifique e siga as políticas de scraping do website +- **Controle de Taxa (Rate Limiting)**: Implemente atrasos entre as requisições para evitar sobrecarregar servidores +- **User Agents**: Use strings de user agent apropriadas para identificar o seu bot +- **Conformidade Legal**: Certifique-se de que suas atividades de scraping estejam em conformidade com os termos de serviço +- **Tratamento de Erros**: Implemente um tratamento de erros robusto para problemas de rede e requisições bloqueadas +- **Qualidade dos Dados**: Valide e limpe os dados extraídos antes de processar + +## **Guia de Seleção de Ferramentas** + +- **Tarefas Simples**: Use `ScrapeWebsiteTool` para extração básica de conteúdo +- **Sites Dinâmicos com JavaScript**: Use `SeleniumScrapingTool` para conteúdo dinâmico +- **Escala & Performance**: Use `FirecrawlScrapeWebsiteTool` para scraping em grande volume +- **Infraestrutura em Nuvem**: Use `BrowserBaseLoadTool` para automação de navegador escalável +- **Fluxos Complexos**: Use `StagehandTool` para interações inteligentes com o navegador diff --git a/docs/pt-BR/tools/web-scraping/oxylabsscraperstool.mdx b/docs/pt-BR/tools/web-scraping/oxylabsscraperstool.mdx new file mode 100644 index 000000000..d8f9ae442 --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/oxylabsscraperstool.mdx @@ -0,0 +1,235 @@ +--- +title: Oxylabs Scrapers +description: > + Os Scrapers da Oxylabs permitem acessar facilmente informações de fontes específicas. Veja abaixo a lista de fontes disponíveis: + - `Amazon Product` + - `Amazon Search` + - `Google Seach` + - `Universal` +icon: globe +--- + +## Instalação + +Obtenha as credenciais criando uma conta na Oxylabs [aqui](https://oxylabs.io). +```shell +pip install 'crewai[tools]' oxylabs +``` +Confira a [Documentação da Oxylabs](https://developers.oxylabs.io/scraping-solutions/web-scraper-api/targets) para mais informações sobre os parâmetros da API. + +# `OxylabsAmazonProductScraperTool` + +### Exemplo + +```python +from crewai_tools import OxylabsAmazonProductScraperTool + +# certifique-se de que as variáveis OXYLABS_USERNAME e OXYLABS_PASSWORD estejam definidas +tool = OxylabsAmazonProductScraperTool() + +result = tool.run(query="AAAAABBBBCC") + +print(result) +``` + +### Parâmetros + +- `query` - código ASIN de 10 caracteres. +- `domain` - domínio de localização da Amazon. +- `geo_location` - local de entrega (_Deliver to_). +- `user_agent_type` - tipo de dispositivo e navegador. +- `render` - ativa o renderizador JavaScript ao definir como `html`. +- `callback_url` - URL do seu endpoint de callback. +- `context` - Configurações avançadas adicionais e controles para requisitos especializados. +- `parse` - retorna os dados já processados quando definido como true. +- `parsing_instructions` - defina sua própria lógica de parsing e transformação de dados que será executada no resultado de scraping HTML. + +### Exemplo avançado + +```python +from crewai_tools import OxylabsAmazonProductScraperTool + +# certifique-se de que as variáveis OXYLABS_USERNAME e OXYLABS_PASSWORD estejam definidas +tool = OxylabsAmazonProductScraperTool( + config={ + "domain": "com", + "parse": True, + "context": [ + { + "key": "autoselect_variant", + "value": True + } + ] + } +) + +result = tool.run(query="AAAAABBBBCC") + +print(result) +``` + +# `OxylabsAmazonSearchScraperTool` + +### Exemplo + +```python +from crewai_tools import OxylabsAmazonSearchScraperTool + +# certifique-se de que as variáveis OXYLABS_USERNAME e OXYLABS_PASSWORD estejam definidas +tool = OxylabsAmazonSearchScraperTool() + +result = tool.run(query="headsets") + +print(result) +``` + +### Parâmetros + +- `query` - termo de busca da Amazon. +- `domain` - Domínio de localização para Bestbuy. +- `start_page` - número da página inicial. +- `pages` - quantidade de páginas a ser recuperada. +- `geo_location` - local de entrega (_Deliver to_). +- `user_agent_type` - tipo de dispositivo e navegador. +- `render` - ativa o renderizador JavaScript ao definir como `html`. +- `callback_url` - URL do seu endpoint de callback. +- `context` - Configurações avançadas adicionais e controles para requisitos especializados. +- `parse` - retorna os dados já processados quando definido como true. +- `parsing_instructions` - defina sua própria lógica de parsing e transformação de dados que será executada no resultado de scraping HTML. + +### Exemplo avançado + +```python +from crewai_tools import OxylabsAmazonSearchScraperTool + +# certifique-se de que as variáveis OXYLABS_USERNAME e OXYLABS_PASSWORD estejam definidas +tool = OxylabsAmazonSearchScraperTool( + config={ + "domain": 'nl', + "start_page": 2, + "pages": 2, + "parse": True, + "context": [ + {'key': 'category_id', 'value': 16391693031} + ], + } +) + +result = tool.run(query='nirvana tshirt') + +print(result) +``` + +# `OxylabsGoogleSearchScraperTool` + +### Exemplo + +```python +from crewai_tools import OxylabsGoogleSearchScraperTool + +# certifique-se de que as variáveis OXYLABS_USERNAME e OXYLABS_PASSWORD estejam definidas +tool = OxylabsGoogleSearchScraperTool() + +result = tool.run(query="iPhone 16") + +print(result) +``` + +### Parâmetros + +- `query` - palavra-chave de busca. +- `domain` - domínio de localização do Google. +- `start_page` - número da página inicial. +- `pages` - número de páginas a ser recuperado. +- `limit` - quantidade de resultados a ser recuperada em cada página. +- `locale` - valor do header `Accept-Language`, que altera o idioma da interface da página de pesquisa do Google. +- `geo_location` - a localização geográfica para a qual o resultado deve ser adaptado. Usar este parâmetro corretamente é extremamente importante para obter os dados corretos. +- `user_agent_type` - tipo de dispositivo e navegador. +- `render` - ativa o renderizador JavaScript ao definir como `html`. +- `callback_url` - URL do seu endpoint de callback. +- `context` - Configurações avançadas adicionais e controles para requisitos especializados. +- `parse` - retorna os dados já processados quando definido como true. +- `parsing_instructions` - defina sua própria lógica de parsing e transformação de dados que será executada no resultado de scraping HTML. + +### Exemplo avançado + +```python +from crewai_tools import OxylabsGoogleSearchScraperTool + +# certifique-se de que as variáveis OXYLABS_USERNAME e OXYLABS_PASSWORD estejam definidas +tool = OxylabsGoogleSearchScraperTool( + config={ + "parse": True, + "geo_location": "Paris, France", + "user_agent_type": "tablet", + } +) + +result = tool.run(query="iPhone 16") + +print(result) +``` + +# `OxylabsUniversalScraperTool` + +### Exemplo + +```python +from crewai_tools import OxylabsUniversalScraperTool + +# certifique-se de que as variáveis OXYLABS_USERNAME e OXYLABS_PASSWORD estejam definidas +tool = OxylabsUniversalScraperTool() + +result = tool.run(url="https://ip.oxylabs.io") + +print(result) +``` + +### Parâmetros + +- `url` - URL do site a ser raspada. +- `user_agent_type` - tipo de dispositivo e navegador. +- `geo_location` - define a geolocalização do proxy para coletar os dados. +- `render` - ativa o renderizador JavaScript ao definir como `html`. +- `callback_url` - URL do seu endpoint de callback. +- `context` - Configurações avançadas adicionais e controles para requisitos especializados. +- `parse` - retorna os dados já processados quando definido como `true`, desde que exista um parser dedicado para o tipo de página da URL fornecida. +- `parsing_instructions` - defina sua própria lógica de parsing e transformação de dados que será executada no resultado de scraping HTML. + +### Exemplo avançado + +```python +from crewai_tools import OxylabsUniversalScraperTool + +# certifique-se de que as variáveis OXYLABS_USERNAME e OXYLABS_PASSWORD estejam definidas +tool = OxylabsUniversalScraperTool( + config={ + "render": "html", + "user_agent_type": "mobile", + "context": [ + {"key": "force_headers", "value": True}, + {"key": "force_cookies", "value": True}, + { + "key": "headers", + "value": { + "Custom-Header-Name": "custom header content", + }, + }, + { + "key": "cookies", + "value": [ + {"key": "NID", "value": "1234567890"}, + {"key": "1P JAR", "value": "0987654321"}, + ], + }, + {"key": "http_method", "value": "get"}, + {"key": "follow_redirects", "value": True}, + {"key": "successful_status_codes", "value": [808, 909]}, + ], + } +) + +result = tool.run(url="https://ip.oxylabs.io") + +print(result) +``` \ No newline at end of file diff --git a/docs/pt-BR/tools/web-scraping/scrapeelementfromwebsitetool.mdx b/docs/pt-BR/tools/web-scraping/scrapeelementfromwebsitetool.mdx new file mode 100644 index 000000000..5b9b243e4 --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/scrapeelementfromwebsitetool.mdx @@ -0,0 +1,139 @@ +--- +title: Ferramenta de Extração de Elementos de Website +description: A `ScrapeElementFromWebsiteTool` permite que agentes CrewAI extraiam elementos específicos de websites usando seletores CSS. +icon: code +--- + +# `ScrapeElementFromWebsiteTool` + +## Descrição + +A `ScrapeElementFromWebsiteTool` foi projetada para extrair elementos específicos de websites utilizando seletores CSS. Esta ferramenta permite que agentes CrewAI capturem conteúdos direcionados de páginas web, tornando-se útil para tarefas de extração de dados em que apenas partes específicas de uma página são necessárias. + +## Instalação + +Para utilizar esta ferramenta, você precisa instalar as dependências necessárias: + +```shell +uv add requests beautifulsoup4 +``` + +## Passos para Começar + +Para usar a `ScrapeElementFromWebsiteTool` de maneira eficaz, siga estes passos: + +1. **Instale as Dependências**: Instale os pacotes necessários com o comando acima. +2. **Identifique os Seletores CSS**: Determine os seletores CSS dos elementos que deseja extrair do site. +3. **Inicialize a Ferramenta**: Crie uma instância da ferramenta com os parâmetros necessários. + +## Exemplo + +O exemplo abaixo demonstra como usar a `ScrapeElementFromWebsiteTool` para extrair elementos específicos de um website: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import ScrapeElementFromWebsiteTool + +# Inicie a ferramenta +scrape_tool = ScrapeElementFromWebsiteTool() + +# Defina um agente que utilizará a ferramenta +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extrair informações específicas de websites", + backstory="Um especialista em web scraping capaz de capturar conteúdos direcionados de páginas web.", + tools=[scrape_tool], + verbose=True, +) + +# Exemplo de tarefa para extrair manchetes de um site de notícias +scrape_task = Task( + description="Extraia as principais manchetes da página inicial da CNN. Use o seletor CSS '.headline' para atingir os elementos de manchete.", + expected_output="Uma lista das principais manchetes da CNN.", + agent=web_scraper_agent, +) + +# Crie e execute o crew +crew = Crew(agents=[web_scraper_agent], tasks=[scrape_task]) +result = crew.kickoff() +``` + +Você também pode inicializar a ferramenta com parâmetros pré-definidos: + +```python Code +# Inicialize a ferramenta com parâmetros pré-definidos +scrape_tool = ScrapeElementFromWebsiteTool( + website_url="https://www.example.com", + css_element=".main-content" +) +``` + +## Parâmetros + +A `ScrapeElementFromWebsiteTool` aceita os seguintes parâmetros durante a inicialização: + +- **website_url**: Opcional. A URL do website a ser extraído. Se fornecido na inicialização, o agente não precisará especificá-lo ao utilizar a ferramenta. +- **css_element**: Opcional. O seletor CSS para os elementos a serem extraídos. Se fornecido na inicialização, o agente não precisará especificá-lo ao utilizar a ferramenta. +- **cookies**: Opcional. Um dicionário contendo cookies a serem enviados com a requisição. Isso pode ser útil para sites que requerem autenticação. + +## Uso + +Ao utilizar a `ScrapeElementFromWebsiteTool` com um agente, o agente precisará fornecer os seguintes parâmetros (a menos que já tenham sido especificados na inicialização): + +- **website_url**: A URL do website a ser extraído. +- **css_element**: O seletor CSS dos elementos a serem extraídos. + +A ferramenta retornará o conteúdo de texto de todos os elementos que correspondam ao seletor CSS, separados por quebras de linha. + +```python Code +# Exemplo de uso da ferramenta com um agente +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extrair elementos específicos de websites", + backstory="Um especialista em web scraping capaz de extrair conteúdo direcionado por meio de seletores CSS.", + tools=[scrape_tool], + verbose=True, +) + +# Crie uma tarefa para o agente extrair elementos específicos +extract_task = Task( + description=""" + Extraia todos os títulos de produtos da seção de produtos em destaque no example.com. + Use o seletor CSS '.product-title' para atingir os elementos de título. + """, + expected_output="Uma lista de títulos de produtos do site", + agent=web_scraper_agent, +) + +# Execute a tarefa utilizando um crew +crew = Crew(agents=[web_scraper_agent], tasks=[extract_task]) +result = crew.kickoff() +``` + +## Detalhes de Implementação + +A `ScrapeElementFromWebsiteTool` utiliza a biblioteca `requests` para buscar a página web e `BeautifulSoup` para analisar o HTML e extrair os elementos especificados: + +```python Code +class ScrapeElementFromWebsiteTool(BaseTool): + name: str = "Read a website content" + description: str = "A tool that can be used to read a website content." + + # Implementation details... + + def _run(self, **kwargs: Any) -> Any: + website_url = kwargs.get("website_url", self.website_url) + css_element = kwargs.get("css_element", self.css_element) + page = requests.get( + website_url, + headers=self.headers, + cookies=self.cookies if self.cookies else {}, + ) + parsed = BeautifulSoup(page.content, "html.parser") + elements = parsed.select(css_element) + return "\n".join([element.get_text() for element in elements]) +``` + +## Conclusão + +A `ScrapeElementFromWebsiteTool` oferece uma maneira poderosa de extrair elementos específicos de websites utilizando seletores CSS. Ao possibilitar que agentes direcionem apenas o conteúdo que necessitam, ela torna as tarefas de web scraping mais eficientes e objetivas. Esta ferramenta é particularmente útil para extração de dados, monitoramento de conteúdos e tarefas de pesquisa em que informações específicas precisam ser extraídas de páginas web. \ No newline at end of file diff --git a/docs/pt-BR/tools/web-scraping/scrapegraphscrapetool.mdx b/docs/pt-BR/tools/web-scraping/scrapegraphscrapetool.mdx new file mode 100644 index 000000000..c5c7fc33b --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/scrapegraphscrapetool.mdx @@ -0,0 +1,196 @@ +--- +title: Ferramenta de Extração Scrapegraph +description: A `ScrapegraphScrapeTool` utiliza a API SmartScraper da Scrapegraph AI para extrair conteúdo de sites de forma inteligente. +icon: chart-area +--- + +# `ScrapegraphScrapeTool` + +## Descrição + +A `ScrapegraphScrapeTool` foi projetada para utilizar a API SmartScraper da Scrapegraph AI e extrair conteúdo de sites de maneira inteligente. Esta ferramenta oferece recursos avançados de web scraping com extração de conteúdo potencializada por IA, tornando-se ideal para coleta de dados direcionada e tarefas de análise de conteúdo. Diferente dos scrapers tradicionais, ela entende o contexto e a estrutura das páginas da web para extrair as informações mais relevantes, com base em instruções em linguagem natural. + +## Instalação + +Para utilizar esta ferramenta, é necessário instalar o cliente Python do Scrapegraph: + +```shell +uv add scrapegraph-py +``` + +Você também precisa definir sua chave de API do Scrapegraph como uma variável de ambiente: + +```shell +export SCRAPEGRAPH_API_KEY="your_api_key" +``` + +Você pode obter uma chave de API em [Scrapegraph AI](https://scrapegraphai.com). + +## Passos para Começar + +Para usar efetivamente a `ScrapegraphScrapeTool`, siga estes passos: + +1. **Instale as dependências**: Instale o pacote necessário usando o comando acima. +2. **Configure a chave de API**: Defina sua chave de API do Scrapegraph como variável de ambiente ou forneça-a durante a inicialização. +3. **Inicialize a ferramenta**: Crie uma instância da ferramenta com os parâmetros necessários. +4. **Defina instruções de extração**: Crie prompts em linguagem natural para guiar a extração de conteúdos específicos. + +## Exemplo + +O exemplo a seguir demonstra como usar a `ScrapegraphScrapeTool` para extrair conteúdo de um site: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import ScrapegraphScrapeTool + +# Initialize the tool +scrape_tool = ScrapegraphScrapeTool(api_key="your_api_key") + +# Define an agent that uses the tool +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract specific information from websites", + backstory="An expert in web scraping who can extract targeted content from web pages.", + tools=[scrape_tool], + verbose=True, +) + +# Example task to extract product information from an e-commerce site +scrape_task = Task( + description="Extract product names, prices, and descriptions from the featured products section of example.com.", + expected_output="A structured list of product information including names, prices, and descriptions.", + agent=web_scraper_agent, +) + +# Create and run the crew +crew = Crew(agents=[web_scraper_agent], tasks=[scrape_task]) +result = crew.kickoff() +``` + +Você também pode inicializar a ferramenta com parâmetros pré-definidos: + +```python Code +# Initialize the tool with predefined parameters +scrape_tool = ScrapegraphScrapeTool( + website_url="https://www.example.com", + user_prompt="Extract all product prices and descriptions", + api_key="your_api_key" +) +``` + +## Parâmetros + +A `ScrapegraphScrapeTool` aceita os seguintes parâmetros durante a inicialização: + +- **api_key**: Opcional. Sua chave de API do Scrapegraph. Se não for fornecida, será procurada a variável de ambiente `SCRAPEGRAPH_API_KEY`. +- **website_url**: Opcional. A URL do site a ser extraído. Se fornecida na inicialização, o agente não precisa especificá-la ao usar a ferramenta. +- **user_prompt**: Opcional. Instruções customizadas para extração de conteúdo. Se fornecida na inicialização, o agente não precisa especificá-la ao usar a ferramenta. +- **enable_logging**: Opcional. Define se o registro (logging) na Scrapegraph deve ser ativado. O padrão é `False`. + +## Uso + +Ao usar a `ScrapegraphScrapeTool` com um agente, será necessário fornecer os seguintes parâmetros (a menos que tenham sido especificados durante a inicialização): + +- **website_url**: A URL do site a ser extraída. +- **user_prompt**: Opcional. Instruções customizadas para extração de conteúdo. O padrão é "Extract the main content of the webpage". + +A ferramenta retornará o conteúdo extraído com base no prompt fornecido. + +```python Code +# Example of using the tool with an agent +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract specific information from websites", + backstory="An expert in web scraping who can extract targeted content from web pages.", + tools=[scrape_tool], + verbose=True, +) + +# Create a task for the agent to extract specific content +extract_task = Task( + description="Extract the main heading and summary from example.com", + expected_output="The main heading and summary from the website", + agent=web_scraper_agent, +) + +# Run the task +crew = Crew(agents=[web_scraper_agent], tasks=[extract_task]) +result = crew.kickoff() +``` + +## Tratamento de Erros + +A `ScrapegraphScrapeTool` pode lançar as seguintes exceções: + +- **ValueError**: Quando a chave da API está ausente ou o formato da URL é inválido. +- **RateLimitError**: Quando o limite de requisições da API é excedido. +- **RuntimeError**: Quando a operação de extração falha (problemas de rede, erros da API). + +Recomenda-se instruir os agentes a lidarem com potenciais erros de forma apropriada: + +```python Code +# Create a task that includes error handling instructions +robust_extract_task = Task( + description=""" + Extract the main heading from example.com. + Be aware that you might encounter errors such as: + - Invalid URL format + - Missing API key + - Rate limit exceeded + - Network or API errors + + If you encounter any errors, provide a clear explanation of what went wrong + and suggest possible solutions. + """, + expected_output="Either the extracted heading or a clear error explanation", + agent=web_scraper_agent, +) +``` + +## Limitações de Taxa + +A API do Scrapegraph possui limites de requisição que variam conforme o seu plano de assinatura. Considere as seguintes boas práticas: + +- Implemente atrasos apropriados entre requisições ao processar múltiplas URLs. +- Trate erros de limite de requisição de forma apropriada em sua aplicação. +- Verifique os limites do seu plano de API no painel do Scrapegraph. + +## Detalhes de Implementação + +A `ScrapegraphScrapeTool` utiliza o cliente Python do Scrapegraph para se comunicar com a API SmartScraper: + +```python Code +class ScrapegraphScrapeTool(BaseTool): + """ + A tool that uses Scrapegraph AI to intelligently scrape website content. + """ + + # Implementation details... + + def _run(self, **kwargs: Any) -> Any: + website_url = kwargs.get("website_url", self.website_url) + user_prompt = ( + kwargs.get("user_prompt", self.user_prompt) + or "Extract the main content of the webpage" + ) + + if not website_url: + raise ValueError("website_url is required") + + # Validate URL format + self._validate_url(website_url) + + try: + # Make the SmartScraper request + response = self._client.smartscraper( + website_url=website_url, + user_prompt=user_prompt, + ) + + return response + # Error handling... +``` + +## Conclusão + +A `ScrapegraphScrapeTool` oferece uma maneira poderosa de extrair conteúdo de sites utilizando o entendimento do formato das páginas pela IA. Ao permitir que os agentes direcionem informações específicas por meio de prompts em linguagem natural, ela torna tarefas de web scraping mais eficientes e focadas. Esta ferramenta é especialmente útil para extração de dados, monitoramento de conteúdo e pesquisas em que informações específicas precisam ser extraídas de páginas web. \ No newline at end of file diff --git a/docs/pt-BR/tools/web-scraping/scrapewebsitetool.mdx b/docs/pt-BR/tools/web-scraping/scrapewebsitetool.mdx new file mode 100644 index 000000000..237671d6a --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/scrapewebsitetool.mdx @@ -0,0 +1,47 @@ +--- +title: Raspar Site +description: O `ScrapeWebsiteTool` foi desenvolvido para extrair e ler o conteúdo de um site especificado. +icon: magnifying-glass-location +--- + +# `ScrapeWebsiteTool` + + + Ainda estamos trabalhando para melhorar as ferramentas, então pode haver comportamentos inesperados ou mudanças futuras. + + +## Descrição + +Uma ferramenta desenvolvida para extrair e ler o conteúdo de um site especificado. Ela é capaz de lidar com diversos tipos de páginas web fazendo requisições HTTP e analisando o conteúdo HTML recebido. +Esta ferramenta pode ser especialmente útil para tarefas de raspagem de dados, coleta de dados ou extração de informações específicas de sites. + +## Instalação + +Instale o pacote crewai_tools + +```shell +pip install 'crewai[tools]' +``` + +## Exemplo + +```python +from crewai_tools import ScrapeWebsiteTool + +# Para permitir a raspagem de qualquer site encontrado durante a execução +tool = ScrapeWebsiteTool() + +# Inicialize a ferramenta com a URL do site, +# assim o agente só poderá raspar o conteúdo do site especificado +tool = ScrapeWebsiteTool(website_url='https://www.example.com') + +# Extraia o texto do site +text = tool.run() +print(text) +``` + +## Argumentos + +| Argumento | Tipo | Descrição | +|:---------------|:---------|:-----------------------------------------------------------------------------------------------------------------------------------| +| **website_url** | `string` | **Obrigatório** URL do site para leitura do arquivo. Esta é a entrada principal da ferramenta, especificando de qual site o conteúdo deve ser raspado e lido. | \ No newline at end of file diff --git a/docs/pt-BR/tools/web-scraping/scrapflyscrapetool.mdx b/docs/pt-BR/tools/web-scraping/scrapflyscrapetool.mdx new file mode 100644 index 000000000..eac6539c0 --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/scrapflyscrapetool.mdx @@ -0,0 +1,220 @@ +--- +title: Ferramenta de Raspagem de Sites Scrapfly +description: A `ScrapflyScrapeWebsiteTool` aproveita a API de web scraping da Scrapfly para extrair conteúdo de sites em diversos formatos. +icon: spider +--- + +# `ScrapflyScrapeWebsiteTool` + +## Descrição + +A `ScrapflyScrapeWebsiteTool` foi desenvolvida para aproveitar a API de web scraping da [Scrapfly](https://scrapfly.io/) para extrair conteúdo de sites. Esta ferramenta oferece recursos avançados de raspagem com suporte a navegador headless, proxies e recursos de bypass de anti-bot. Permite extrair dados de páginas web em vários formatos, incluindo HTML bruto, markdown e texto simples, sendo ideal para uma ampla variedade de tarefas de raspagem de sites. + +## Instalação + +Para utilizar esta ferramenta, é necessário instalar o Scrapfly SDK: + +```shell +uv add scrapfly-sdk +``` + +Você também precisará obter uma chave de API da Scrapfly registrando-se em [scrapfly.io/register](https://www.scrapfly.io/register/). + +## Passos para Começar + +Para usar a `ScrapflyScrapeWebsiteTool` de forma eficaz, siga estas etapas: + +1. **Instale as Dependências**: Instale o Scrapfly SDK usando o comando acima. +2. **Obtenha a Chave de API**: Cadastre-se na Scrapfly para obter sua chave de API. +3. **Inicialize a Ferramenta**: Crie uma instância da ferramenta com sua chave de API. +4. **Configure os Parâmetros de Raspagem**: Personalize os parâmetros de raspagem conforme suas necessidades. + +## Exemplo + +O exemplo a seguir demonstra como usar a `ScrapflyScrapeWebsiteTool` para extrair conteúdo de um site: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import ScrapflyScrapeWebsiteTool + +# Initialize the tool +scrape_tool = ScrapflyScrapeWebsiteTool(api_key="your_scrapfly_api_key") + +# Define an agent that uses the tool +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract information from websites", + backstory="An expert in web scraping who can extract content from any website.", + tools=[scrape_tool], + verbose=True, +) + +# Example task to extract content from a website +scrape_task = Task( + description="Extract the main content from the product page at https://web-scraping.dev/products and summarize the available products.", + expected_output="A summary of the products available on the website.", + agent=web_scraper_agent, +) + +# Create and run the crew +crew = Crew(agents=[web_scraper_agent], tasks=[scrape_task]) +result = crew.kickoff() +``` + +Você também pode personalizar os parâmetros de raspagem: + +```python Code +# Example with custom scraping parameters +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract information from websites with custom parameters", + backstory="An expert in web scraping who can extract content from any website.", + tools=[scrape_tool], + verbose=True, +) + +# The agent will use the tool with parameters like: +# url="https://web-scraping.dev/products" +# scrape_format="markdown" +# ignore_scrape_failures=True +# scrape_config={ +# "asp": True, # Bypass scraping blocking solutions, like Cloudflare +# "render_js": True, # Enable JavaScript rendering with a cloud headless browser +# "proxy_pool": "public_residential_pool", # Select a proxy pool +# "country": "us", # Select a proxy location +# "auto_scroll": True, # Auto scroll the page +# } + +scrape_task = Task( + description="Extract the main content from the product page at https://web-scraping.dev/products using advanced scraping options including JavaScript rendering and proxy settings.", + expected_output="A detailed summary of the products with all available information.", + agent=web_scraper_agent, +) +``` + +## Parâmetros + +A `ScrapflyScrapeWebsiteTool` aceita os seguintes parâmetros: + +### Parâmetros de Inicialização + +- **api_key**: Obrigatório. Sua chave de API da Scrapfly. + +### Parâmetros de Execução + +- **url**: Obrigatório. A URL do site a ser raspado. +- **scrape_format**: Opcional. O formato em que o conteúdo da página será extraído. As opções são "raw" (HTML), "markdown" ou "text". O padrão é "markdown". +- **scrape_config**: Opcional. Um dicionário contendo opções adicionais de configuração de raspagem da Scrapfly. +- **ignore_scrape_failures**: Opcional. Determina se as falhas de raspagem devem ser ignoradas. Se definido como `True`, a ferramenta irá retornar `None` ao invés de lançar uma exceção caso ocorra uma falha na raspagem. + +## Opções de Configuração Scrapfly + +O parâmetro `scrape_config` permite personalizar o comportamento da raspagem com as seguintes opções: + +- **asp**: Ativa o bypass de proteção anti-scraping. +- **render_js**: Ativa a renderização de JavaScript com um navegador headless na nuvem. +- **proxy_pool**: Seleciona um pool de proxies (por exemplo, "public_residential_pool", "datacenter"). +- **country**: Seleciona a localização do proxy (por exemplo, "us", "uk"). +- **auto_scroll**: Rola automaticamente a página para carregar conteúdo lazy-loaded. +- **js**: Executa código JavaScript personalizado via o navegador headless. + +Para uma lista completa de opções de configuração, consulte a [documentação da API Scrapfly](https://scrapfly.io/docs/scrape-api/getting-started). + +## Uso + +Ao usar a `ScrapflyScrapeWebsiteTool` com um agente, o agente deverá fornecer a URL do site a ser raspado e pode opcionalmente especificar o formato e opções adicionais de configuração: + +```python Code +# Example of using the tool with an agent +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract information from websites", + backstory="An expert in web scraping who can extract content from any website.", + tools=[scrape_tool], + verbose=True, +) + +# Create a task for the agent +scrape_task = Task( + description="Extract the main content from example.com in markdown format.", + expected_output="The main content of example.com in markdown format.", + agent=web_scraper_agent, +) + +# Run the task +crew = Crew(agents=[web_scraper_agent], tasks=[scrape_task]) +result = crew.kickoff() +``` + +Para um uso mais avançado com configurações personalizadas: + +```python Code +# Create a task with more specific instructions +advanced_scrape_task = Task( + description=""" + Extract content from example.com with the following requirements: + - Convert the content to plain text format + - Enable JavaScript rendering + - Use a US-based proxy + - Handle any scraping failures gracefully + """, + expected_output="The extracted content from example.com", + agent=web_scraper_agent, +) +``` + +## Tratamento de Erros + +Por padrão, a `ScrapflyScrapeWebsiteTool` irá lançar uma exceção se a raspagem falhar. Os agentes podem ser instruídos a tratar falhas de forma mais flexível especificando o parâmetro `ignore_scrape_failures`: + +```python Code +# Create a task that instructs the agent to handle errors +error_handling_task = Task( + description=""" + Extract content from a potentially problematic website and make sure to handle any + scraping failures gracefully by setting ignore_scrape_failures to True. + """, + expected_output="Either the extracted content or a graceful error message", + agent=web_scraper_agent, +) +``` + +## Detalhes de Implementação + +A `ScrapflyScrapeWebsiteTool` utiliza o Scrapfly SDK para interagir com a API Scrapfly: + +```python Code +class ScrapflyScrapeWebsiteTool(BaseTool): + name: str = "Scrapfly web scraping API tool" + description: str = ( + "Scrape a webpage url using Scrapfly and return its content as markdown or text" + ) + + # Implementation details... + + def _run( + self, + url: str, + scrape_format: str = "markdown", + scrape_config: Optional[Dict[str, Any]] = None, + ignore_scrape_failures: Optional[bool] = None, + ): + from scrapfly import ScrapeApiResponse, ScrapeConfig + + scrape_config = scrape_config if scrape_config is not None else {} + try: + response: ScrapeApiResponse = self.scrapfly.scrape( + ScrapeConfig(url, format=scrape_format, **scrape_config) + ) + return response.scrape_result["content"] + except Exception as e: + if ignore_scrape_failures: + logger.error(f"Error fetching data from {url}, exception: {e}") + return None + else: + raise e +``` + +## Conclusão + +A `ScrapflyScrapeWebsiteTool` oferece uma forma poderosa de extrair conteúdo de sites usando as avançadas capacidades de web scraping da Scrapfly. Com recursos como suporte a navegador headless, proxies e bypass de anti-bot, ela consegue lidar com sites complexos e extrair conteúdo em diversos formatos. Esta ferramenta é especialmente útil em tarefas de extração de dados, monitoramento de conteúdo e pesquisa, onde a raspagem confiável de sites é necessária. \ No newline at end of file diff --git a/docs/pt-BR/tools/web-scraping/seleniumscrapingtool.mdx b/docs/pt-BR/tools/web-scraping/seleniumscrapingtool.mdx new file mode 100644 index 000000000..69d37e309 --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/seleniumscrapingtool.mdx @@ -0,0 +1,195 @@ +--- +title: Selenium Scraper +description: O `SeleniumScrapingTool` foi desenvolvido para extrair e ler o conteúdo de um site específico utilizando o Selenium. +icon: clipboard-user +--- + +# `SeleniumScrapingTool` + + + Esta ferramenta está atualmente em desenvolvimento. Conforme aprimoramos suas capacidades, os usuários podem encontrar comportamentos inesperados. + Seu feedback é inestimável para que possamos melhorar. + + +## Descrição + +O `SeleniumScrapingTool` foi criado para tarefas de raspagem web de alta eficiência. +Permite a extração precisa de conteúdo de páginas web utilizando seletores CSS para direcionar elementos específicos. +Seu design atende a uma ampla gama de necessidades de scraping, oferecendo flexibilidade para trabalhar com qualquer URL de site fornecida. + +## Instalação + +Para utilizar esta ferramenta, é necessário instalar o pacote CrewAI tools e o Selenium: + +```shell +pip install 'crewai[tools]' +uv add selenium webdriver-manager +``` + +Você também precisará ter o Chrome instalado em seu sistema, pois a ferramenta utiliza o Chrome WebDriver para automação do navegador. + +## Exemplo + +O exemplo a seguir demonstra como usar o `SeleniumScrapingTool` com um agente CrewAI: + +```python Code +from crewai import Agent, Task, Crew, Process +from crewai_tools import SeleniumScrapingTool + +# Inicializa a ferramenta +selenium_tool = SeleniumScrapingTool() + +# Define um agente que utiliza a ferramenta +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract information from websites using Selenium", + backstory="An expert web scraper who can extract content from dynamic websites.", + tools=[selenium_tool], + verbose=True, +) + +# Exemplo de tarefa para extrair conteúdo de um site +scrape_task = Task( + description="Extract the main content from the homepage of example.com. Use the CSS selector 'main' to target the main content area.", + expected_output="The main content from example.com's homepage.", + agent=web_scraper_agent, +) + +# Cria e executa o crew +crew = Crew( + agents=[web_scraper_agent], + tasks=[scrape_task], + verbose=True, + process=Process.sequential, +) +result = crew.kickoff() +``` + +Você também pode inicializar a ferramenta com parâmetros predefinidos: + +```python Code +# Inicializa a ferramenta com parâmetros predefinidos +selenium_tool = SeleniumScrapingTool( + website_url='https://example.com', + css_element='.main-content', + wait_time=5 +) + +# Define um agente que utiliza a ferramenta +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract information from websites using Selenium", + backstory="An expert web scraper who can extract content from dynamic websites.", + tools=[selenium_tool], + verbose=True, +) +``` + +## Parâmetros + +O `SeleniumScrapingTool` aceita os seguintes parâmetros durante a inicialização: + +- **website_url**: Opcional. A URL do site a ser raspado. Se fornecido durante a inicialização, o agente não precisará especificá-lo ao utilizar a ferramenta. +- **css_element**: Opcional. O seletor CSS dos elementos a serem extraídos. Se fornecido durante a inicialização, o agente não precisará especificá-lo ao utilizar a ferramenta. +- **cookie**: Opcional. Um dicionário contendo informações de cookies, útil para simular uma sessão logada e acessar conteúdo restrito. +- **wait_time**: Opcional. Especifica o atraso (em segundos) antes da raspagem, permitindo que o site e qualquer conteúdo dinâmico carreguem totalmente. O padrão é `3` segundos. +- **return_html**: Opcional. Indica se o conteúdo HTML deve ser retornado em vez do texto simples. O padrão é `False`. + +Ao usar a ferramenta com um agente, o agente precisará fornecer os seguintes parâmetros (a menos que tenham sido especificados durante a inicialização): + +- **website_url**: Obrigatório. A URL do site a ser raspado. +- **css_element**: Obrigatório. O seletor CSS dos elementos a serem extraídos. + +## Exemplo de Integração com Agente + +Aqui está um exemplo mais detalhado de como integrar o `SeleniumScrapingTool` com um agente CrewAI: + +```python Code +from crewai import Agent, Task, Crew, Process +from crewai_tools import SeleniumScrapingTool + +# Inicializa a ferramenta +selenium_tool = SeleniumScrapingTool() + +# Define um agente que utiliza a ferramenta +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract and analyze information from dynamic websites", + backstory="""You are an expert web scraper who specializes in extracting + content from dynamic websites that require browser automation. You have + extensive knowledge of CSS selectors and can identify the right selectors + to target specific content on any website.""", + tools=[selenium_tool], + verbose=True, +) + +# Cria uma tarefa para o agente +scrape_task = Task( + description=""" + Extract the following information from the news website at {website_url}: + + 1. The headlines of all featured articles (CSS selector: '.headline') + 2. The publication dates of these articles (CSS selector: '.pub-date') + 3. The author names where available (CSS selector: '.author') + + Compile this information into a structured format with each article's details grouped together. + """, + expected_output="A structured list of articles with their headlines, publication dates, and authors.", + agent=web_scraper_agent, +) + +# Executa a tarefa +crew = Crew( + agents=[web_scraper_agent], + tasks=[scrape_task], + verbose=True, + process=Process.sequential, +) +result = crew.kickoff(inputs={"website_url": "https://news-example.com"}) +``` + +## Detalhes de Implementação + +O `SeleniumScrapingTool` utiliza o Selenium WebDriver para automatizar interações com o navegador: + +```python Code +class SeleniumScrapingTool(BaseTool): + name: str = "Read a website content" + description: str = "A tool that can be used to read a website content." + args_schema: Type[BaseModel] = SeleniumScrapingToolSchema + + def _run(self, **kwargs: Any) -> Any: + website_url = kwargs.get("website_url", self.website_url) + css_element = kwargs.get("css_element", self.css_element) + return_html = kwargs.get("return_html", self.return_html) + driver = self._create_driver(website_url, self.cookie, self.wait_time) + + content = self._get_content(driver, css_element, return_html) + driver.close() + + return "\n".join(content) +``` + +A ferramenta executa as seguintes etapas: +1. Cria uma instância do Chrome em modo headless +2. Navega até a URL especificada +3. Aguarda o tempo especificado para permitir o carregamento da página +4. Adiciona cookies se fornecidos +5. Extrai conteúdo baseado no seletor CSS +6. Retorna o conteúdo extraído como texto ou HTML +7. Encerra a instância do navegador + +## Tratamento de Conteúdo Dinâmico + +O `SeleniumScrapingTool` é especialmente útil para extrair sites com conteúdo dinâmico carregado via JavaScript. Usando uma instância real de navegador, ele pode: + +1. Executar JavaScript na página +2. Aguardar o carregamento do conteúdo dinâmico +3. Interagir com elementos se necessário +4. Extrair conteúdo que não estaria disponível usando apenas requisições HTTP simples + +Você pode ajustar o parâmetro `wait_time` para garantir que todo o conteúdo dinâmico tenha sido carregado antes da extração. + +## Conclusão + +O `SeleniumScrapingTool` fornece uma maneira poderosa de extrair conteúdo de sites utilizando automação de navegador. Ao permitir que agentes interajam com sites como um usuário real, ele facilita a raspagem de conteúdo dinâmico que seria difícil ou impossível de extrair utilizando métodos mais simples. Esta ferramenta é especialmente útil para pesquisas, coleta de dados e tarefas de monitoramento que envolvem aplicações web modernas com conteúdo renderizado por JavaScript. \ No newline at end of file diff --git a/docs/pt-BR/tools/web-scraping/spidertool.mdx b/docs/pt-BR/tools/web-scraping/spidertool.mdx new file mode 100644 index 000000000..ca7349c46 --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/spidertool.mdx @@ -0,0 +1,91 @@ +--- +title: Spider Scraper +description: O `SpiderTool` foi projetado para extrair e ler o conteúdo de um site especificado usando o Spider. +icon: spider-web +--- + +# `SpiderTool` + +## Descrição + +[Spider](https://spider.cloud/?ref=crewai) é o [scraper](https://github.com/spider-rs/spider/blob/main/benches/BENCHMARKS.md#benchmark-results) e crawler de código aberto mais rápido que retorna dados prontos para LLM. +Ele converte qualquer site em HTML puro, markdown, metadados ou texto e permite que você faça crawling com ações personalizadas utilizando IA. + +## Instalação + +Para usar o `SpiderTool` você precisa baixar o [Spider SDK](https://pypi.org/project/spider-client/) +e também o SDK `crewai[tools]`: + +```shell +pip install spider-client 'crewai[tools]' +``` + +## Exemplo + +Este exemplo mostra como você pode usar o `SpiderTool` para permitir que seu agente faça scraping e crawling de websites. +Os dados retornados pela API do Spider já estão prontos para LLM, então não é necessário fazer nenhuma limpeza adicional. + +```python Code +from crewai_tools import SpiderTool + +def main(): + spider_tool = SpiderTool() + + searcher = Agent( + role="Web Research Expert", + goal="Find related information from specific URL's", + backstory="An expert web researcher that uses the web extremely well", + tools=[spider_tool], + verbose=True, + ) + + return_metadata = Task( + description="Scrape https://spider.cloud with a limit of 1 and enable metadata", + expected_output="Metadata and 10 word summary of spider.cloud", + agent=searcher + ) + + crew = Crew( + agents=[searcher], + tasks=[ + return_metadata, + ], + verbose=2 + ) + + crew.kickoff() + +if __name__ == "__main__": + main() +``` + +## Argumentos +| Argumento | Tipo | Descrição | +|:---------------------|:----------|:------------------------------------------------------------------------------------------------------------------------------------------------------| +| **api_key** | `string` | Especifica a chave da API do Spider. Se não for definida, procura por `SPIDER_API_KEY` nas variáveis de ambiente. | +| **params** | `object` | Parâmetros opcionais para a requisição. O padrão é `{"return_format": "markdown"}` para otimizar o conteúdo para LLMs. | +| **request** | `string` | Tipo de requisição a ser realizada (`http`, `chrome`, `smart`). `smart` tem como padrão HTTP, alterando para renderização JavaScript se necessário. | +| **limit** | `int` | Máximo de páginas a serem rastreadas por site. Defina como `0` ou omita para ilimitado. | +| **depth** | `int` | Profundidade máxima do crawl. Defina como `0` para sem limite. | +| **cache** | `bool` | Habilita cache HTTP para acelerar execuções repetidas. O padrão é `true`. | +| **budget** | `object` | Define limites baseados em caminho para páginas rastreadas, ex.: `{"*":1}` apenas para a página raiz. | +| **locale** | `string` | Localidade da requisição, ex.: `en-US`. | +| **cookies** | `string` | Cookies HTTP para a requisição. | +| **stealth** | `bool` | Habilita modo furtivo para requisições Chrome para evitar detecção. O padrão é `true`. | +| **headers** | `object` | Headers HTTP como um mapa de chave-valor para todas as requisições. | +| **metadata** | `bool` | Armazena metadados sobre as páginas e conteúdos, auxiliando interoperabilidade com IA. O padrão é `false`. | +| **viewport** | `object` | Define as dimensões de viewport do Chrome. O padrão é `800x600`. | +| **encoding** | `string` | Especifica o tipo de codificação, ex.: `UTF-8`, `SHIFT_JIS`. | +| **subdomains** | `bool` | Inclui subdomínios no crawl. O padrão é `false`. | +| **user_agent** | `string` | User agent HTTP personalizado. Padrão é um agente aleatório. | +| **store_data** | `bool` | Habilita o armazenamento dos dados para a requisição. Sobrescreve `storageless` quando definido. O padrão é `false`. | +| **gpt_config** | `object` | Permite à IA gerar ações de crawl, com encadeamento de etapas opcional via array para `"prompt"`. | +| **fingerprint** | `bool` | Habilita fingerprint avançado para o Chrome. | +| **storageless** | `bool` | Impede todo o armazenamento de dados, incluindo embeddings de IA. O padrão é `false`. | +| **readability** | `bool` | Pré-processa conteúdo para leitura via [Mozilla’s readability](https://github.com/mozilla/readability). Melhora o conteúdo para LLMs. | +| **return_format** | `string` | Formato para retorno dos dados: `markdown`, `raw`, `text`, `html2text`. Use `raw` para formato padrão da página. | +| **proxy_enabled** | `bool` | Habilita proxies de alta performance para evitar bloqueios em nível de rede. | +| **query_selector** | `string` | CSS query selector para extração de conteúdo a partir do markup. | +| **full_resources** | `bool` | Baixa todos os recursos vinculados ao site. | +| **request_timeout** | `int` | Timeout em segundos para as requisições (5-60). O padrão é `30`. | +| **run_in_background**| `bool` | Executa a requisição em segundo plano. Útil para armazenamento de dados e acionamento de crawls no dashboard. Não tem efeito se `storageless` estiver definido. \ No newline at end of file diff --git a/docs/pt-BR/tools/web-scraping/stagehandtool.mdx b/docs/pt-BR/tools/web-scraping/stagehandtool.mdx new file mode 100644 index 000000000..b4b3066fa --- /dev/null +++ b/docs/pt-BR/tools/web-scraping/stagehandtool.mdx @@ -0,0 +1,241 @@ +--- +title: Ferramenta Stagehand +description: Ferramenta de automação web que integra o Stagehand ao CrewAI para interação e automação em navegadores +icon: hand +--- + +# Visão Geral + +A `StagehandTool` integra o framework [Stagehand](https://docs.stagehand.dev/get_started/introduction) com o CrewAI, permitindo que agentes interajam com sites e automatizem tarefas no navegador utilizando instruções em linguagem natural. + +## Visão Geral + +O Stagehand é um poderoso framework de automação de navegador criado pela Browserbase que permite aos agentes de IA: + +- Navegar por sites +- Clicar em botões, links e outros elementos +- Preencher formulários +- Extrair dados de páginas web +- Observar e identificar elementos +- Realizar fluxos de trabalho complexos + +A StagehandTool encapsula o SDK Python do Stagehand para fornecer aos agentes do CrewAI capacidades de controle do navegador através de três primitivas principais: + +1. **Act**: Executar ações como clicar, digitar ou navegar +2. **Extract**: Extrair dados estruturados de páginas web +3. **Observe**: Identificar e analisar elementos na página + +## Pré-requisitos + +Antes de utilizar esta ferramenta, certifique-se de que você possui: + +1. Uma conta [Browserbase](https://www.browserbase.com/) com chave API e ID de projeto +2. Uma chave API para um LLM (OpenAI ou Anthropic Claude) +3. O SDK Python do Stagehand instalado + +Instale a dependência necessária: + +```bash +pip install stagehand-py +``` + +## Uso + +### Implementação Básica + +A StagehandTool pode ser implementada de duas maneiras: + +#### 1. Usando Context Manager (Recomendado) + + A abordagem de context manager é recomendada, pois garante o encerramento adequado dos recursos mesmo em caso de exceções. + + +```python +from crewai import Agent, Task, Crew +from crewai_tools import StagehandTool +from stagehand.schemas import AvailableModel + +# Initialize the tool with your API keys using a context manager +with StagehandTool( + api_key="your-browserbase-api-key", + project_id="your-browserbase-project-id", + model_api_key="your-llm-api-key", # OpenAI or Anthropic API key + model_name=AvailableModel.CLAUDE_3_7_SONNET_LATEST, # Optional: specify which model to use +) as stagehand_tool: + # Create an agent with the tool + researcher = Agent( + role="Web Researcher", + goal="Find and summarize information from websites", + backstory="I'm an expert at finding information online.", + verbose=True, + tools=[stagehand_tool], + ) + + # Create a task that uses the tool + research_task = Task( + description="Go to https://www.example.com and tell me what you see on the homepage.", + agent=researcher, + ) + + # Run the crew + crew = Crew( + agents=[researcher], + tasks=[research_task], + verbose=True, + ) + + result = crew.kickoff() + print(result) +``` + +#### 2. Gerenciamento Manual de Recursos + +```python +from crewai import Agent, Task, Crew +from crewai_tools import StagehandTool +from stagehand.schemas import AvailableModel + +# Initialize the tool with your API keys +stagehand_tool = StagehandTool( + api_key="your-browserbase-api-key", + project_id="your-browserbase-project-id", + model_api_key="your-llm-api-key", + model_name=AvailableModel.CLAUDE_3_7_SONNET_LATEST, +) + +try: + # Create an agent with the tool + researcher = Agent( + role="Web Researcher", + goal="Find and summarize information from websites", + backstory="I'm an expert at finding information online.", + verbose=True, + tools=[stagehand_tool], + ) + + # Create a task that uses the tool + research_task = Task( + description="Go to https://www.example.com and tell me what you see on the homepage.", + agent=researcher, + ) + + # Run the crew + crew = Crew( + agents=[researcher], + tasks=[research_task], + verbose=True, + ) + + result = crew.kickoff() + print(result) +finally: + # Explicitly clean up resources + stagehand_tool.close() +``` + +## Tipos de Comando + +A StagehandTool suporta três tipos diferentes de comando para tarefas específicas de automação web: + +### 1. Comando Act + +O tipo de comando `act` (padrão) permite interações em páginas web como clicar em botões, preencher formulários e navegar. + +```python +# Perform an action (default behavior) +result = stagehand_tool.run( + instruction="Click the login button", + url="https://example.com", + command_type="act" # Default, so can be omitted +) + +# Fill out a form +result = stagehand_tool.run( + instruction="Fill the contact form with name 'John Doe', email 'john@example.com', and message 'Hello world'", + url="https://example.com/contact" +) +``` + +### 2. Comando Extract + +O tipo de comando `extract` recupera dados estruturados de páginas web. + +```python +# Extract all product information +result = stagehand_tool.run( + instruction="Extract all product names, prices, and descriptions", + url="https://example.com/products", + command_type="extract" +) + +# Extract specific information with a selector +result = stagehand_tool.run( + instruction="Extract the main article title and content", + url="https://example.com/blog/article", + command_type="extract", + selector=".article-container" # Optional CSS selector +) +``` + +### 3. Comando Observe + +O tipo de comando `observe` identifica e analisa elementos da página web. + +```python +# Find interactive elements +result = stagehand_tool.run( + instruction="Find all interactive elements in the navigation menu", + url="https://example.com", + command_type="observe" +) + +# Identify form fields +result = stagehand_tool.run( + instruction="Identify all the input fields in the registration form", + url="https://example.com/register", + command_type="observe", + selector="#registration-form" +) +``` + +## Opções de Configuração + +Personalize o comportamento da StagehandTool com estes parâmetros: + +```python +stagehand_tool = StagehandTool( + api_key="your-browserbase-api-key", + project_id="your-browserbase-project-id", + model_api_key="your-llm-api-key", + model_name=AvailableModel.CLAUDE_3_7_SONNET_LATEST, + dom_settle_timeout_ms=5000, # Wait longer for DOM to settle + headless=True, # Run browser in headless mode + self_heal=True, # Attempt to recover from errors + wait_for_captcha_solves=True, # Wait for CAPTCHA solving + verbose=1, # Control logging verbosity (0-3) +) +``` + +## Boas Práticas + +1. **Seja Específico**: Forneça instruções detalhadas para melhores resultados +2. **Escolha o Tipo de Comando Apropriado**: Selecione o comando correto para sua tarefa +3. **Use Selectors**: Utilize seletores CSS para aumentar a precisão +4. **Divida Tarefas Complexas**: Separe fluxos de trabalho complexos em múltiplas chamadas da ferramenta +5. **Implemente Tratamento de Erros**: Adicione tratamento de erros para possíveis problemas + +## Solução de Problemas + +Problemas comuns e soluções: + +- **Problemas de Sessão**: Verifique as chaves de API tanto da Browserbase quanto do provedor de LLM +- **Elemento Não Encontrado**: Aumente o `dom_settle_timeout_ms` para páginas mais lentas +- **Falhas em Ações**: Use o `observe` para identificar corretamente os elementos antes +- **Dados Incompletos**: Refine as instruções ou forneça seletores específicos + +## Recursos Adicionais + +Para dúvidas sobre a integração com o CrewAI: +- Participe da comunidade [Slack do Stagehand](https://stagehand.dev/slack) +- Abra uma issue no [repositório Stagehand](https://github.com/browserbase/stagehand) +- Visite a [documentação do Stagehand](https://docs.stagehand.dev/) \ No newline at end of file